Best practices for REST API design (2020) • Hacker News Board

Re: Best practices for REST API design (2020)

#111

Post by Toutouxc » Mon, Feb 22, 2021, 5:56 PM UTC

capableweb wrote: post #87

spelunker wrote: post #81

Earlier quoted context omitted.

> Webmachine is an application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management provided by mochiweb, and provides a simple and clean way to connect that to your application's behavior. Great buzzwords, I have no idea what this project actually does.

It's less buzzwords and more that you're required to understand HTTP and probably be a programmer to understand what's being said. For you and other non-programmers: https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... (particularly https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... ) Also knowing that mochiweb is a library for doing HTTP servers would help. Once you've learned these two, the…

> For you and other non-programmers

> Once you've learned these two, the sentence immediately becomes clear

> it can sound like mumbo-jumbo, but I'm sure it makes sense for them, since they are professionals

Did you just link a person to a two-kilometer long page about HTTP, assumed they're not a programmer and almost accused them of not being professional enough, because they haven't heard of some Erlang library?

> application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management

I'm a web developer and my reaction was exactly the same. What the heck does this thing actually do?

Re: Best practices for REST API design (2020)

#112

Post by pier25 » Mon, Feb 22, 2021, 5:59 PM UTC

patrickcteng wrote: post #47

fc373745 wrote: post #9

Earlier quoted context omitted.

Never understood the hype around GraphQL. You want to know how to halve your performance and responses/s on your service? add graphql. All things that GraphQL claims to do can be implemented in RESTful services easily. If you want specificity in your query fetching, just add query params or put them in the request body If you want schema validations, there are many libraries that help you with that. And if you want d…

I love this comment so much. With GraphQL, you're just pushing N+1 calls and figuring out the mental contortion needed to support all the graphy-ness from non-graph structures. Most that say GraphQL is the bees-knees must be an FE developer. There's nothing wrong with that, but GraphQL is just NOT as cracked up to be.

I'm not a GraphQL advocate and barely use it myself, but the N+1 problem has been solved in many server implementations.

Eg: Hasura.

https://hasura.io/blog/architecture-of-a-high-performance-gr...

Re: Best practices for REST API design (2020)

#113

Post by _nothing » Mon, Feb 22, 2021, 5:59 PM UTC

tstrimple wrote: post #102

masklinn wrote: post #82

Earlier quoted context omitted.

I’d say they’re right: cursors are way better for an API. Pages are way better for a person. This here is about an API.

How often do people really jump to an arbitrary page? I'd say filtering / searching capabilities are far more important for users than paging.

It depends? If I'm looking for a new desk on IKEA's online catalog then I care more about filtering/searching, but if I'm reading through a conversation on a forum and want to be able to link to certain sections then I want that paginated.

Re: Best practices for REST API design (2020)

#114

Post by pionar » Mon, Feb 22, 2021, 5:59 PM UTC

capableweb wrote: post #87

spelunker wrote: post #81

Earlier quoted context omitted.

> Webmachine is an application layer that adds HTTP semantic awareness on top of the excellent bit-pushing and HTTP syntax-management provided by mochiweb, and provides a simple and clean way to connect that to your application's behavior. Great buzzwords, I have no idea what this project actually does.

It's less buzzwords and more that you're required to understand HTTP and probably be a programmer to understand what's being said. For you and other non-programmers: https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... (particularly https://tools.ietf.org/id/draft-ietf-httpbis-semantics-03.ht... ) Also knowing that mochiweb is a library for doing HTTP servers would help. Once you've learned these two, the…

I'm a programmer, and I know HTTP quite well. I know what HTTP semantics are, and this sentence is still gibberish to me.

I'd wager the reason I don't is because I'm not that familiar with the erlang ecosystem, so have no idea what mochiweb is, and don't know what this does differently.

Your first sentence was quite condescending, FYI, not sure if it was meant to be.

Re: Best practices for REST API design (2020)

#115

Post by p_l » Mon, Feb 22, 2021, 5:59 PM UTC

YesThatTom2 wrote: post #101

API Practices If You Hate Your Customers https://cacm.acm.org/magazines/2019/12/241052-api-practices-...

Pretty good, though I disagree with their opinion on SOAP ;)

Many REST APIs have problems for the same reason SOAP had, and it involves lack of deliberate API design and abuse of "automagic code generation"

Re: Best practices for REST API design (2020)

#116

Post by sidpatil » Mon, Feb 22, 2021, 6:00 PM UTC

snarfy wrote: post #41

I always have mixed feelings about using plurals for naming. Pluralization in English is extremely inconsistent. cat -> cats, dog -> dogs, child -> children, person -> people, etc. It makes my code feel inconsistent too. Sometimes I use more specific typing to resolve this, e.g. PersonList , but I'm not sure that's any better.

I don't see a problem with writing "childs" or "persons".

In this scenario, consistency is more useful than grammatical correctness [1]. And the simpler pluralization logic makes it easier for non-English speakers to work with the codebase.

Re: Best practices for REST API design (2020)

#117

Post by waspight » Mon, Feb 22, 2021, 6:03 PM UTC

motogpjimbo wrote: post #23

numlock86 wrote: post #5

> Then if we try to submit the payload with the email value that already exists in users, we’ll get a 400 response status code with a 'User already exists' message to let users know that the user already exists. With that information, the user can correct the action by changing the email to something that doesn’t exist. I was always under the impression that 409 would be the "correct" code here, while you'd use 400 i…

Ironically, your comment is a perfect illustration of one of the problems with REST - its tendency to provoke discussion about things that don't actually matter in practice. No user cares whether an error response came back with a 400 or a 409 status, or what those codes even mean. It's madness that as a profession we spend so much of our employers' time and money on trivial things that deliver no value whatsoever. R…

But for graphql you will have the problem of naming the mutations instead. That is also a debate...

Re: Best practices for REST API design (2020)

#118

Post by Xelbair » Mon, Feb 22, 2021, 6:04 PM UTC

Octoth0rpe wrote: post #56

nojvek wrote: post #44

I’d say REST apis should also support selections. E.g I only care about these fields. It’s the #1 reason why graphql is so popular. You only fetch what you want. But I have missed feelings about graphql. I wish they didn’t invent a new language, it was just json. I’ve encountered so many little bugs because graphql parsing is different between different servers. Ideas of graphql are great, implementation seems over c…

> It’s the #1 reason why graphql is so popular. You only fetch what you want. It's certainly one of the main sales points for graphql. On the flip side, I've never been frustrated by getting too many fields back from an API. I suppose if I was developing exclusively in extremely bandwidth limited contexts where getting back only 2 fields rather than 50 actually made a difference, I might care. It just seems like such…

I was frustrated immensely due to that.

I could fetch the objects in bulk request.. except they didn't have the field i needed when fetched in bulk. So i had to do bulk fetch, where each object was pretty big and then fetch them again individually.

If that service supported graphql i could easily just grab what i need, without hammering the poor already over-utilized server.

This kind of issues prop up constantly especially if you use on-perm hosting.

Re: Best practices for REST API design (2020)

#119

Post by pugworthy » Mon, Feb 22, 2021, 6:04 PM UTC

JoshuaEddy wrote: post #89

Looks like a ripoff of this post from June 2019: https://www.merixstudio.com/blog/best-practices-rest-api-dev...

It's a common design style it seems. O'Reilly's REST API Design Rulebook reads similarly...

https://www.oreilly.com/library/view/rest-api-design/9781449...

Re: Best practices for REST API design (2020)

#120

Post by pionar » Mon, Feb 22, 2021, 6:04 PM UTC

Longwelwind wrote: post #48

seliopou wrote: post #7

I interrupted my reading at 'Accept and respond with JSON' to write this comment, before I skipped over that section and returned to reading the rest. Folks that aren't aware of Webmachine should take a look: https://github.com/webmachine/webmachine The 'Accept' header should determine the response type, but content negotiation is something that few bother to implement. Webmachine does that for you, among other thing…

What is the usefulness of this feature? The only advantage I see is that your clients can choose the format they want to work with, but since the serialization format is just a message format that has no impact on the code, and that most of them have a bijective transformation between them, I don't see the point. If it feels like a lot of work (Or the added complexity of a moving part, if using the tool you linked) f…

If you don't care about others using your API, then don't do it. If you do, follow the standard which says you SHOULD have a Content-Type if there is a body to your response.