REST API – How to Implement a RESTful API That Updates a List with Exclusions and Additions?

djangorest

We have an application where there is an API to create a document with a POST and update it with a PUT. There is a separate API to share document with users.

Now, How should we approach updating the list of users who the document is shared with ?

Should it be a POST or PUT that actually deletes the whole association and replace it with new ?

How are things like these sanely implemented in a RESTful way ?

Best Answer

When using the HTTP protocol for your REST API (the common situation), PUT is used to replace a resource and POST to modify a resource.

If the list of document recipients is modeled as a sub-resource of your document, you can either use POST to add users to the list or PUT to replace the whole list, whatever is most convenient to you and/or the users of your API.

If the list of document recipients is not modeled as a sub-resource, but is a simple property of the document, then you should use POST (on the document) to modify the list without overwriting the rest of the document resource.

Related Solutions

Creating RESTful Websites with HTML Forms

The 'New Post' button would go to a form for the user to input the information for a new post. When the user submits that form the browser rightly sends that data via HTTP POST (use POST for create).

An edit submission would use PUT or PATCH depending on whether it is a replace (delete the missing properties) or update (only change the submitted properties), respectively.

We usually make an XMLHTTPRequest (XHR) using JavaScript for events other than GET or POST.

jQuery.ajax('/products/42', {method: 'PUT', data: product_data});

jQuery Docs: http://api.jquery.com/jquery.ajax/

Additionally, Rails will use a '_method' param in POSTs to force a different action on the server ( like PUT or PATCH).

RESTful API/Data Modeling – How to model an subordinate resource that will only ever have one element

The POST /documents/<documentId>/revisions endpoint has to also modify the DocumentDrafts table to reflect the fact that the document is now in a "clean" state and can be modified by another user

Different layer. It is important to understand that it is usually not desirable to tightly couple the API layer to the service and/or data layers.

The PUT /documents/<documentId>/draft endpoint breaks a few rules of REST including the use of the singular word "draft" (because there can only be one draft of a document)

There is no such rule. For starters, REST says exactly nothing about what URIs should look like. Beyond that, it is generally accepted in web API design that singular words are reasonable when only a single instance of the resource exists.

In your shoes, I'd use these endpoints:

/documents
/documents/{id}
/documents/{id}/draft
/revisions
/revisions/{id}

A user can GET a document. This will contain a link or a subresource with the most recent revision. To start editing, they POST to draft. This will either return 201 Created (they are now editing) or 409 Conflict (somebody else is already editing). The user who is editing will PUT to draft. To cancel editing without saving, the user can DELETE draft. To commit the draft, they POST to /revisions. A side effect of this will be to DELETE the draft. Alternately, you can require a manual DELETE of draft by the client to terminate the edit.

Now the only problem you have is what happens when the user starts an edit and goes on vacation without cancelling or committing it. :-)

Best Answer

Related Solutions

Creating RESTful Websites with HTML Forms

RESTful API/Data Modeling – How to model an subordinate resource that will only ever have one element

Related Topic