Comment by stupidcar | Hacker News Reader

Comment by stupidcar | Hacker News Reader

Pure REST is great for toy examples, where every domain entity fits neatly into a resource and every operation is a CRUD one that can be represented as an HTTP verb. So there is a million tutorials explaining how to build a REST API for a blog with BlogPost and Author resources, or an ordering system with Customer and Order resources.

However, when you move beyond these simple examples and start trying to build a REST API for a messy, complex system, you immediately run into trouble. How do you deal with non-CRUD operations? How do you deal with long running processes? Or entities in an indeterminate state? How do you aggregate multiple resources into individual request/responses for performance? How do you de-duplicate identical entities within an aggregated response? How do you return only particular fields? How do you handle paging and filtering? How do you handle transactions? How do you handle authentication and security restrictions?

All of these things can be solved, but by the time you've finished, your API will be far from easy to understand. It will need a load of accompanying documentation to make it usable, and will have a bunch of weird corners where you're initiating operations as a side effect of setting entity flags, or you've noun-ed verbs in order to turn an abstract operation into a resource. E.g. PUT /server-reboot-attempt.

Pure REST is great for toy examples, where every domain entity fits neatly into a resource and every operation is a CRUD one that can be represented as an HTTP verb. So there is a million tutorials explaining how to build a REST API for a blog with BlogPost and Author resources, or an ordering system with Customer and Order resources.

In my opinion REST is fat more easier to understand for non-CRUD resources. The whole idea of CRUD makes REST sometimes seem like an HTTP adapter to the database.

However, when you move beyond these simple examples and start trying to build a REST API for a messy, complex system, you immediately run into trouble. How do you deal with non-CRUD operations? How do you deal with long running processes?

You POST the work to be done to a resource. That resource returns a URL where you can follow the state of the long running process. An alternative would be to provide a Webhook that will be called when the long running process has finished.

Or entities in an indeterminate state?

Same principle, return its actual state on a GET request (polling). Or use a Webhook (push).

How do you aggregate multiple resources into individual request/responses for performance?

Use HAL embedding or multipart.

How do you de-duplicate identical entities within an aggregated response?

Use the hypertext caching pattern in your caching layer or proxy. Use the URL as a unique key.

How do you return only particular fields?

Use HAL embedding, query parameters or a subresource.

How do you handle paging and filtering?

Use link relations and query parameters.

How do you handle transactions?

That's exactly what POST is for.

How do you handle authentication and security restrictions?

Provide a token header over https. Avoid magic URLs based on cookie state (i.e. even when you are logged in as mike your account details still are at https://example.org/user/mike/account). Restrictions are a product of the token and the requested URL.

All of these things can be solved, but by the time you've finished, your API will be far from easy to understand.

That is true, it won't be easy to understand, but it will be simple, composable, discoverabe and scalable.

It will need a load of accompanying documentation to make it usable

In my experience the opposite is true, true REST (which includes hypermedia controls) need less accompanying documentation. It makes resources more predictable and less dependendent on URLs.

All of these things can be solved, but by the time you've finished, your API will be far from easy to understand. It will need a load of accompanying documentation to make it usable, and will have a bunch of weird corners where you're initiating operations as a side effect of setting entity flags, or you've noun-ed verbs in order to turn an abstract operation into a resource. E.g. PUT /server-reboot-attempt.

In stead of making a separate resource for every action it would suffice to make one that receives actions by POSTing to it. You can respond with a URL that represents its progress. And it will also save a lot of unnecessary links or hardcoded URLs.

Any book / link where you think we can get more details about your responses?

Most O'Reilly books about REST are really good. If you want to be more practical I suggest looking for simple ways to introduce hypermedia controls. In my opinion the HAL JSON standard is the easiest to understand: https://www.google.com/search?q=hal+json

> How do you deal with non-CRUD operations?

There is no such thing as a non-CRUD operation in a well-modeled domain. Actions in the domain are entities in the model and, therefore, are subjects of CRUD operations (often just Create and Read, but Update and Delete can also be sensible.)

> How do you deal with long running processes?

As entities that can be Created and Read.

> Or entities in an indeterminate state?

By returning a representation of the applicable wavefunction.

> How do you aggregate multiple resources into individual request/responses for performance?

By defining resources that are aggregates of other resources, and including, among the available representations for such resources, representations that include the subelements directly rather than only by reference.

This is analogous, in the RelationalDBs, to defining views (or set-valued functions, depending on the type of aggregation you are doing.)

> How do you de-duplicate identical entities within an aggregated response?

Whether or how you do this depends on the representation chosen.

> How do you return only particular fields?

By returning a representation that includes only the projection of the base resource that is of interest. I suspect the question you mean to ask, however, is how you specify a request for such a projection in REST over HTTP (REST is not tied to a particular protocol, but HTTP is the most popular one used with the architecture, and does have some particular issues in this particular case), and there are a couple of obvious alternatives:

1) Treat this as a request to create a subordinate resource to the base resource, and do it via POST, or 2) Recognize that this (like the use case met now by PATCH) is a gap in the existing HTTP method set that requires a workaround, and add a HTTP extension method (preferably, one proposed as an RFC with general semantics), such as something similar to WebDAV's REPORT or SEARCH (but not so application-specific.) REST doesn't -- with an extensible protocol like HTTP -- mean you have to be limited by the base protocol, it just means you have to be judicious in your use of extensions. [0]

> How do you handle paging and filtering?

Same answer as the previous question (in fact, paging and filtering are essentially the same thing as the previous question.)

> How do you handle transactions?

A unit of work that is logically linked in the domain is an entity in the domain that can be Created, Read, Updated, and Deleted (particularly C = BEGIN , U = COMMIT, D = ROLLBACK.) Actions within the transaction can either reference the transaction in resource representations or be subordinate resources to the transaction itself, depending on context.

> How do you handle authentication and security restrictions?

Generally, Authentication is communications-protocol dependent and how security restrictions are enforced is outside of the scope of REST.

[0] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... : "A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field."

Reply on news.ycombinator.com