Regarding #9 BE consistent: this is the consequence of allowing chaos to take over. There are far fewer individuals trying to reduce complexity compared to those who are adding to it. And, the effort required to resolve these inconsistencies is 10x than that needed to create them.
How to (and how not to) design REST APIs
71–80 of 153 posts
Re: How to (and how not to) design REST APIs
#72Earlier quoted context omitted.
how do you differentiate between plural vs singular of: `GET /staff` ?
I don't? It's fine. I'm also fine just adding an 's' to many words that have unusual plurals; English is flexible, and "persons" is a perfectly acceptable substitute for "people". That said, I don't love your example. Staff does have a plural, staffs - as in, the separate staffs of multiple organizations.
what's your opinion of using suffix like '_list' to differentiate it ?
ie:
GET /species
and
GET /species_list
?
Re: How to (and how not to) design REST APIs
#73The author makes a good point about not throwing 404s.. a logical extension of this is that it should apply to all the other error codes. Does REST encourage the use of http error codes?
Re: How to (and how not to) design REST APIs
#74Regarding rule #4 (DON'T return arrays as top level responses), I feel that meta information returned about the collection really fits the responsibility of HTTP headers. This is similar to existing response headers like Content-Length and Content-Range. REST clients already work with “out-of-band” information like HTTP statuses and If-Modified-Since. Do we always have add yet another layer to nest meta information in?
Re: How to (and how not to) design REST APIs
#75“RESTful” API design is mostly bike-shedding. There’s no standard. Every REST API looks different. Clients have to refer to documentation anyway, so consistent URL patterns achieve nothing. People waste large amounts of time over totally inconsequential minutiae like whether to use singular or plural words in URLs. Separating idempotent calls from non-idempotent calls is useful, but REST overcomplicates this. All tha…
What's your view on this,
https://news.ycombinator.com/item?id=38103310#38104983
?
Re: How to (and how not to) design REST APIs
#76Regarding rule #4 (DON'T return arrays as top level responses), I feel that meta information returned about the collection really fits the responsibility of HTTP headers. This is similar to existing response headers like Content-Length and Content-Range. REST clients already work with “out-of-band” information like HTTP statuses and If-Modified-Since. Do we always have add yet another layer to nest meta information i…
While you may be right about headers, I think the point the article makes about easily adding more fields to the result without breaking backwards compatibility is pretty compelling.
Re: How to (and how not to) design REST APIs
#77Regarding rule #4 (DON'T return arrays as top level responses), I feel that meta information returned about the collection really fits the responsibility of HTTP headers. This is similar to existing response headers like Content-Length and Content-Range. REST clients already work with “out-of-band” information like HTTP statuses and If-Modified-Since. Do we always have add yet another layer to nest meta information i…
I struggle with this concept with RabbitMQ as well. The AMQP 0-9-1 protocol used by RabbitMQ has a headers table at the protocol level for user-defined key-value pairs that can be associated with the message payload. The same question applies here, what should go in this protocol header table vs on the message.
One concern I have about using these user-defined headers is that in my designs I'll typically remove the payload from the AMQP envelope and propogate just the payload to the business logic. What to do if the headers need to be included in the business logic. It seems risky to use the headers at the protocol level.
Any thoughts?
Re: How to (and how not to) design REST APIs
#78Regarding rule #4 (DON'T return arrays as top level responses), I feel that meta information returned about the collection really fits the responsibility of HTTP headers. This is similar to existing response headers like Content-Length and Content-Range. REST clients already work with “out-of-band” information like HTTP statuses and If-Modified-Since. Do we always have add yet another layer to nest meta information i…
While you may be right about headers, I think the point the article makes about easily adding more fields to the result without breaking backwards compatibility is pretty compelling.
It’s a good rule for non-collection resources and for the elements of collection resources, but I was specifically thinking about collections, where all top-level information (apart from the elements of the collection themselves) is necessarily meta information about the returned data, and not part of the returned data proper.
Re: How to (and how not to) design REST APIs
#79This falls down as soon as it makes a fundamental misunderstanding of what makes a REST api into a REST api. It gives this as a ‘bad’ example: GET /v3/application/shops/{shop_id}/listings/{listing_id}/properties With the justification that “The {listing_id} is globally unique; there's no reason for {shop_id} to be part of the URL. “ No the point of the API is that /v3/application/shops/{shop_id}/listings/{listing_id}…
You apparently have not actually used Etsy's API.
No, the shop id is not in fact part of the globally unique identifier of an Etsy listing, and the properties are not dependent on the shop. Etsy listings have a 1:N relationship with Etsy shops.
The API was a mistake, which they are slowly correcting - they've already changed:
GET /v3/application/shops/{shop_id}/listings/{listing_id}
GET /v3/application/listings/{listing_id}
Managing permissions using the hierarchy of a URL is silly at best, dangerous at worst. The first thing any attacker will do is plug in an alternative shop id and see if it grants access to the non-permitted listing. If permissions are attached to the shop (and for Etsy, they are) the server needs to load the listing, figure out the associated shop, and then check permissions. The client cannot be trusted to provide the correct shop id, so there's no point in asking for it.
Re: How to (and how not to) design REST APIs
#80Earlier quoted context omitted.
Because you can add new properties for response-level global information on an object, but not on an array.
Obviously if it was global, but if not, you'd include it in the objects in the array, no? This is not a question of schema evolution per se.
Yes. The TFA argument is about top-level information, for example when paging through a collection. Personally I think HTTP headers could fit the purpose for such meta information.