Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

How to (and how not to) design REST APIs

github.com

Post reply on HN
Print view View original

81–90 of 153 posts

Re: How to (and how not to) design REST APIs

#81

Post by layer8 »

waynesonfire wrote: post #77
layer8 wrote: post #74

Regarding 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 p…

Assuming that these key-value pairs are not necessarily related to the request semantics (e.g. like `hasMore` in TFA), and also are a unbounded set of potential user-defined key names, then I think it’s appropriate to nest them in the response body. It also sounds like the response is a single message in your case, so the array question doesn’t come up.

You could also place these user-defined headers in a special property of the message, e.g.:

    { // message object
        "_headerTable": { … },
        // actual message properties here
    }
It is a common convention to use underscore-prefixed JSON properties for such meta data.

Re: How to (and how not to) design REST APIs

#82

Post by recursivedoubts »

DrDroop wrote: post #53
nesarkvechnep wrote: post #3

Half of the points are complete bs. URLs don’t matter in REST. What matters are link relations.

I would go even further and say that REST is BS Most people understand REST as a format for URLs and a particular semantics for HTTP methods. While it can be perfectly ok to design an api like person?id=123. This is the way that Postgrest does it, which works, and makes certain things like entities with composite primary keys way easier. Other, like OP, think REST isn't going far enough in that HATEOAS is what "reall…

You are still building an API, it's just a hypermedia API:

https://htmx.org/essays/hypermedia-apis-vs-data-apis/

REST was coined to describe the web. It has been misapplied to JSON APIs over HTTP, and the way we got here is a funny story:

https://htmx.org/essays/how-did-rest-come-to-mean-the-opposi...

other related essays:

https://htmx.org/essays/hypermedia-clients/

https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

https://intercoolerjs.org/2016/01/18/rescuing-rest.html

Re: How to (and how not to) design REST APIs

#83

Post by stickfigure »

prisonality wrote: post #72
stickfigure wrote: post #69

Earlier quoted context omitted.

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 ?

Seems weird.

Of all the rules, #1 one is by far the most arbitrary and least important. But it's also a thoroughly established convention. If you want to present "this is a normal, boring API with few surprises" to your clients, I wouldn't recommend odd collection suffixes.

But it's not going to fundamentally change the usability of your API, unlike many of the other rules.

Re: How to (and how not to) design REST APIs

#84

Post by recursivedoubts »

I’d just like to interject for a moment. What you’re referring to as REST, is in fact, JSON/RPC, or as I’ve recently taken to calling it, REST-less. JSON is not a hypermedia unto itself, but rather a plain data format made useful by out of band information as defined by swagger documentation or similar.

Many computer users work with a canonical version of REST every day, without realizing it. Through a peculiar turn of events, the version of REST which is widely used today is often called “The Web”, and many of its users are not aware that it is basically the REST-ful architecture, defined by Roy Fielding.

There really is a REST, and these people are using it, but it is just a part of The Web they use. REST is the network architecture: hypermedia encodes the state of resources for hypermedia clients. JSON is an essential part of Single Page Applications, but useless by itself; it can only function in the context of a complete API specification. JSON is normally used in combination with SPA libraries: the whole system is basically RPC with JSON added, or JSON/RPC. All these so-called “REST-ful” APIs are really JSON/RPC.

respectfully, https://htmx.org/essays/#hypermedia-and-rest

Re: How to (and how not to) design REST APIs

#85

Post by Arch-TK »

tkiolp4 wrote: post #39
lmz wrote: post #12

Earlier quoted context omitted.

"REST" is supposed to be an architectural style reflecting the Web as used by humans. Humans don't normally manually construct URLs. They navigate based on links from an entry point. (See also: https://hypermedia.systems/hypermedia-components/#_self_desc... )

The vast majority of people using REST do not follow its original definition, so the original definition doesn’t matter anymore. It’s like human languages: REST is whatever we make of it, regardless of what academics say.

Sure. But then what words do you use to describe actual REST?

This keeps happening and all it does it cause confusion.

It's one thing to make up new words for new concepts so you can more easily refer to them in a conversation.

It's another thing entirely to give a word a vague but similar meaning without any clear way to differentiate between the original specific and new extremely nebulous concept.

Re: How to (and how not to) design REST APIs

#86

Post by jameshart »

stickfigure wrote: post #79
jameshart wrote: post #65

This 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} to: GET /v3/application/listings/{…

That’s a critique of Etsy’s API not of good REST resource identification.

No plugging in a shop you have permission to doesn’t work if your resources are hierarchical any more than plugging ~/passwd let’s you read /etc/passwd because you have read access to your home directory. Those are different resources and one of them exists and is locked down and the other one doesn’t exist.

Re: How to (and how not to) design REST APIs

#87

Post by bonzini »

prisonality wrote: post #72
stickfigure wrote: post #69

Earlier quoted context omitted.

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 ?

The case of having a singular at the end of a GET is so rare that it should be easy to disambiguate. I have a project where one of the main objects is a "series", it's clear what "GET /series" and "GET /series/ID" means to anyone that has seen a REST API.

Re: How to (and how not to) design REST APIs

#88

Post by hotnfresh »

postalrat wrote: post #42

A missing rule is "DON'T use strings for timestamps". Which implies "Rule #6: DO use strings for all identifiers" is not good advice.

I disagree that that should be a rule. String timestamps are fine as long as you pick a common standard for the format. Preferable to Unix epoch-seconds or -millis or whatever, at least, if that's what you're suggesting instead. If you're serving over HTTP you clearly don't need the minuscule efficiency gain, and those are a pain (for a human) to read & write.

Re: How to (and how not to) design REST APIs

#90

Post by buggy6257 »

nine_zeros wrote: post #55
tkiolp4 wrote: post #46

Earlier quoted context omitted.

Agree. But I pick REST (or “json over http”) any day of the week instead of graphql, soap, grpc, etc.

Graphql just for the sake of graphql is a disaster for backend engineers.

I want to hug you right now.
Post reply on HN