9

I am creating a WCF webservice with WcF Authentication Service and the first set of functions I need is to manage an inbox for a client. The client will be determined by the authentication.

This is my attempt at a RESTful design of the API:

https://api.mydomain.com/v1/inbox/messages (GET)

Returns a page of results in the inbox with an optional search filter applied

  • Count - number of records per page
  • Page - page to start on
  • Sort - (optional) field to sort on
  • Search - (optional) text to search for

https://api.mydomain.com/v1/inbox/mark (POST)

Marks one or more messages read or unread

  • Action - MarkRead or MarkUnread
  • MessageIDs - list of Message IDs to mark

https://api.mydomain.com/v1/inbox/archive (POST)

Archives one or more messages

  • MessageIDs - list of Message IDs to archive

Am I doing this right? If not, what would be a better way to design this interface?

Jason
  • 16,739
  • 23
  • 87
  • 137
  • Sounds like read and unread can be part of your second URL? `https://api.mydomain.com/v1/inbox/mark/read` and `https://api.mydomain.com/v1/inbox/mark/unread` – Amir Raminfar Sep 13 '11 at 22:27
  • Should they be two separate functions or one function with a parameter (which is more the norm in RESTful API)? – Jason Sep 13 '11 at 22:29
  • if you do what I suggested then it would be two end points right? as in two URLs. But the system can handle them with the same method. – Amir Raminfar Sep 13 '11 at 22:31
  • Okay, thanks... is it better to have two end points (one for every action)? Should they be POST if they change data? Is the rest correct? – Jason Sep 13 '11 at 22:32
  • 1
    If they change data they should be POST or PUT. Here is a link on comparison when to use which http://stackoverflow.com/questions/630453/put-vs-post-in-rest and http://jcalcote.wordpress.com/2008/10/16/put-or-post-the-rest-of-the-story/ – Amir Raminfar Sep 13 '11 at 22:36

3 Answers3

1

Martin Fowler has a good summary of the Richardson Maturity Model and what it takes to make a RESTful service. Jan referenced one of Roy Fielding's posts, but there are some steps to take care of in addition to hypermedia (and HATEOAS).

With reference to the Richardson model, I think your API would need some changes to get to "Level 3" (duh duh duhhhh). The /v1/inbox/messages collection looks sound, and only supporting GET indicates that it's a read-only resource to the user. However POSTing actions and IDs to the /v1/inbox/mark and /v1/inbox/archive is only tunneling RPC-style services over HTTP - "Level 0" in the article.

I'd suggest something like the following as being a naive, non-hypermedia (i.e. "Level 2") API:

  • To retrieve a list of summary information of all of the messages (in all folders):

    GET /v1/messages HTTP/1.1
Host: api.mydomain.com

    Response:

    content-type: text/xml

<?xml version="1.0"?>
<messages>
  <message subject="Subject" unread="true" id="1234" folder="inbox" />
  <message subject="Hello, world" unread="false" id="24" folder="inbox" />
  ...
</messages>

  • To retrieve a full message:

    GET /v1/messages/1234 HTTP/1.1
Host: api.mydomain.com

    Response:

    content-type: text/xml

<?xml version="1.0"?>
<message subject="Subject" unread="true" id="1234" folder="inbox">
  Hi, this is the message.
</message>

  • To edit a message (e.g. to mark it as read and move it to the archive folder):

    POST /v1/inbox/messages/1234 HTTP/1.1
Host: api.mydomain.com
content-type: text/xml

<?xml version="1.0"?>
<message id="1234" unread="false" folder="archive" />

    Note: here I'm intentionally using POST instead of PUT to indicate a partial update.

Other things that stand out as needing attention are:

  • Hypermedia responses and media types. Frankly this is better explained by others (e.g. the REST In Practice book, or the InfoQ Coffee Cup example by the same authors), but in short your responses should indicate to the client what other actions might be possible from the response to their most recent request, and allow them to discover the entire API from just a single URI. As an example, there is an implication of folders collections above. If GET /v1/messages/1234 returned:

    <message subject="Subject" unread="true" id="1234" folder="inbox" >
  Message text here.

  <link rel="folder" href="http://api.mydomain.com/v1/folders/inbox" />
</message>

    then the client would have a concrete example of a URI to try an OPTIONS on, and a good idea of what might be there.

  • Response codes and content: 200 OK is obvious. Respond with 403 Forbidden if the user is not authorized to view a particular message, 404 Not Found if the message ID doesn't exist. Every time you return an error, give the client some indication of how to correct their request (if at all possible).

Ian
  • 977
  • 8
  • 14
0

Regarding to read/unread part I do not think you need a post. I think you need put method https://api.mydomain.com/v1/inbox/messageId/Read https://api.mydomain.com/v1/inbox/messageId/Unread

Post needed when creating a new record and you want to update

For archive part I am agree. Just remember to return result for the archiving process.

Gregory Nozik
  • 3,296
  • 3
  • 32
  • 47
0

Roy's POST is helpful when facing such questions: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Hence: focus on defining media type(s) instead of coupling your clients to predefined sets of URIs. They need not be registered, to be useful, BTW.

Maybe also see http://www.nordsc.com/ext/classification_of_http_based_apis.html#http-type-one

Jan Algermissen
  • 4,930
  • 4
  • 26
  • 39