Hacker News Reader

Comment by suprgeek | Hacker News Reader

Whenever I see a REST book I always have the same set of questions:

1) How do I call operations such as Clean, Restart etc not the regular CRUD ones? I may have to end up doing a variation of POST - is that RESTful (whatever that means)?

2) Whats a good way to simulate a "transaction" semantic (In as much as possible over a distributed systems with arbitrary nodes i.e. the Web)

3) How Do I call a long running operation- a create that takes more than a minute for example? Return a "tracking id" and keep GET querying?

4)How do I version my API? What is the one true way?

5)How about automated discovery of the API? Is it SWAGGER or WADL or something else?

6) Is a nested hierarchical URL scheme a good Idea? How much do you nest one resource under the other?

7) Are you a Teapot?

Many other questions that I have never seen answered properly

View on HN

1,2,3) Strictly, they are all resources. A "Clean" resource can be created (POST|PUT) describing what to clean. It will create (201) that resource which you can read (get the status), even delete (cancel the action), or change (POST/PUT) again. Take a look at the http://restcookbook.com/Resources/asynchroneous-operations/, which basically describes this.

4) According to Roy Fielding, you don't (you don't version your website), but you can add/change/delete your resource versioning. I'd (and many) prefer the accept-header for this, but there are as many different versioning systems as there are API's.

5: hypermedia / HATEOAS

6: sure. If it makes sense. Not everything is hierarchical, but things that are, do it.

7: 418

The reason for this was figure out myself how certain things should be done in a "restful" way. To be honest, truly restful is an utopia imho, but on a daily basis, I see many advantages (as well explained in Roy fieldings dissertation) about the restful setup in comparision to a non-rest setup.

Pragmatically, since I'm not building API's for HUGE system (and even if they are or will become so), it's still possible to use non-rest components (yes, even verb-like systems and url versioning like /api/v1/.

I consider rest to be like the pirates code: not so much a strict law, but more as a guideline.

Just today I read about postgrest[1], REST-like API for postgresql.

While it is not REST by what this cookbook says (it uses JSON), it provides very different view at how API should work.[2]

Postgrest versions the API using HTTP accept header. It provides "pagination" not using XML attributes, but using HTTP range headers, as the standard allows to specify partial content in items, not just in bytes. The author also suggest that deeply nested URLs are a bad idea, because most data (like relational data) is actually flat.

It might provide interesting "second opinion" to what this cookbook says. It doesn't say anything about transactions,

[1]: https://github.com/begriffs/postgrest [2]: http://begriffs.com/posts/2014-12-30-intro-to-postgrest.html

>HTTP range headers, as the standard allows to specify partial content in items, not just in bytes

When doing HTTP Range requests, you'd use HEAD to get the complete length first. If your range requests are in items, is it still in spec to specify Content-Length in items too? I'd think that would break some clients.

Add:

8) How to represent relations (esp. many-to-many) between non-hierarchical resources? The answers I have seen are either variations of "represent the relation as a resource" (is tying the relation resource's lifetime to that of the things related RESTful?), or "represent the relation as a property on both resources" (is it RESTful to reflect the update of a property on one object in another?).

Reply on news.ycombinator.com