[Pki-devel] TPS REST interface design

[Ade Lee]

1. One of the decisions you made was to allow admins, agents and
operators to access the same resources.  So, unlike the rest of the java
subsystems, we will have /tps/rest/tokens as opposed
to /tps/rest/agent/tokens or /tps/rest/admin/tokens

One reason one might want to add /agent or /admin is if the content of
GET /tps/tokens/X is different for admins/agents/operators.

So what is the difference between op=search and op=search_admin, op=view
and op=view_admin, op=show and op=show_admin? etc.

Is there any case where those differences need be preserved?

2. You use PUT /tps/rest/tokens/X as the operation to modify tokens.
Usually REST semantics imply that the resource passed in to the PUT
operation essentially replace the resource at the server.

Is that your intention?  I'm guessing that the resource that would be
passed in is the token object returned in GET /tps/rest/tokens/foo.
It would help if you defined what a token resource was.

Or is your intention to send in something with an "action" parameter -
in which case, the correct operation is a POST?

3.  Should we be worried about a XSS attack here for modifying the state
of the token?  My guess is that we need to take advantage of the nonce
mechanism, in which case, token state modification will require two
steps.

4. You should also note that we will be sending back BAD_REQUEST (401?)
when the token state transition is not permitted.

5. In the response to PUT /tokens/X, it is not necessary to return the
state of the token.  Rather, you should return a URL pointer to the
newly modified resource.  The same comment applies to the other PUT
operations as well. 

6. Same question about XSS for add/remove token/ add/remove user.

7.  Note that the difference between op=view_activity,
op=view_activity_all etc. is in the types of activities that are
visible.  This should be handled seamlessly in the logic used to select
activity records from the db.

8.  For the configuration items - audit config, profiles, profile
mappings, connections, authenticators, I wonder if it makes things
clearer to put them under a config bucket .. like /tps/rest/config/audit
for example.

9. Is there a mapping between Profile and Profile Mapping operations and
the old operations?  Please put that in so we can see whether we have
complete coverage.  In particular, I do not see an operation to
approve/enable a profile.  This is important because we have Common
Criteria requirements that two users are involved in the approval of a
profile.  In our case, IIRC we implemented it such that an admin can
configure a profile but an agent must approve it.

10.  In POST /tps/rest/profilemappings, you return the location of the
profile mappings as well as the contents of the profile mapping
resource.  You should just return the location.  In fact, its probably
better to just return locations in general.  The client would then use
GET to fetch the details if needed.  This comment applies to many of the
resources.

11. In the PUT /tps/rest/config, we have requirements for having than
one user to approve changes.  Admins make changes and agents approve
them if I recall correctly.  You should look at the differences between
the agent and admin pages.


 
On Tue, 2013-06-25 at 13:15 -0500, Endi Sukma Dewata wrote:
> Hi,
> 
> This is the initial draft of the TPS REST interface design:
> http://pki.fedoraproject.org/wiki/TPS_REST_Interface
> 
> Please take a look and let me know if you have any comments. Thanks!
>