How to design a REST API for a webservice whose RPC method has overloaded meanings?

Question

Existing XML webservice

• Processes XML-RPC style requests in which an operation element which identifies the method to dispatch to. For example:

  <protocol><operation>810</operation><user>...</user></protocol>

• The number of parameters vary.

• The XML-RPC handler interprets the 810 token to mean two things. If it receives an element <user> as a child element of <protocol>, it CREATEs an account. If it receives the element <userExisting> instead, it will attempt to log in the user.

New JSON REST API design

• I want to keep this to one REST endpoint e.g. /api/foobar
• I can translate a user creation to a PUT /api/foobar/${user}
• A user removal to a DELETE /api/foobar/${user}
• My current design is to do a POST /api/foobar/${user} with a body { "op":"login" } for logging in and similarly for logout, the body { "op":"logout" } will be sent.

What do you people think of this? Brickbats and bouquets are welcomed with constructive comments.

Answer 1

Overloaded POST for a RESTful API is a bit of a kludge, if you can avoid it. For the purposes of login, I would prefer to try to maintain statelessness - this would mean requiring the client to pass HTTP authorization on each request (this means passing the correct Authorization header each time). You use one of the usual authentication methods such as Basic on the first request.

Answer 2

The end point should be at the URI api/users for all CRUD operations. DELETE and PUT are not supported in forms built with HTML 4 but if you are using Javascript to communicate then you'll be fine but you might want to expose create and delete operations via POST as well (possibly passing _method=PUT|DELETE in the POST payload).

For login the end point should be api/login but you would be better off using HTTP authentication here.

Asking for design reviews on stack overflow is good but you would be better off reading up on RESTful architectures to avoid wrong turns.

Answer 3

How about something like this for login and logout

POST /api/foobar/${user}/loginrequests

POST /api/foobar/${user}/logoutrequests

The server does not actually have to create a "request" resource if you don't want, but later you may change you mind and want to keep a record of logins and logouts.