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

Re: Best practices for REST API design (2020)

#11

Post by btmcnellis » Mon, Feb 22, 2021, 4:01 PM UTC

quercusa wrote: post #8

throw_m239339 wrote: post #6

All these "best practices" are exactly why I embraced GraphQL quickly and flushed "REST" down the toilets for big projects (http+json is fine for small ones, since no lib overhead). GraphQL is unashamedly the new SOAP. I.e. we have a spec, not a series of "best practices" thus endless architectural debates where people are shamed for 'doing it the wrong way' online. - Accept and respond with JSON: No, why? what if I…

> GraphQL is unashamedly the new SOAP ...may not be the advertising you think it is.

A kinder way to put it might be "SOAP with the benefit of hindsight."

Re: Best practices for REST API design (2020)

#12

Post by pfarrell » Mon, Feb 22, 2021, 4:02 PM UTC

babyyoda wrote: post #4

Great post. Nothing flashy, walks through basics and principles. I do love the simplicity of REST and unless you need some graph would recommend folks stick with it over GraphQL

When I looked into implementing GraphQL, it didn’t seem to require the data I was serving be a graph. I found the big difference with REST was that GQL allows the consumer to define the properties returned rather than having backend engineers have to think through every use case. It wasn’t enough of a killer feature to risk the timeline on that project, so my experience is limited.

Re: Best practices for REST API design (2020)

#13

Post by ed25519FUUU » Mon, Feb 22, 2021, 4:04 PM UTC

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…

Isn’t 409 if you’re trying to update an existing record (PUT) and not create a new record (POST)?

The ambiguity is probably why most people just use 400 and call it a day.

Re: Best practices for REST API design (2020)

#14

Post by dmitriid » Mon, Feb 22, 2021, 4:05 PM UTC

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…

> The 'Accept' header should determine the response type

Also, the HTTP decision diagram: https://github.com/for-GET/http-decision-diagram/tree/master...

Re: Best practices for REST API design (2020)

#15

Post by throwoutttt » Mon, Feb 22, 2021, 4:05 PM UTC

GraphQL is far superior for development speed, API flexibility and extensibility, authorisation, discovery, testing, and less bugs.

Re: Best practices for REST API design (2020)

#16

Post by kitd » Mon, Feb 22, 2021, 4:07 PM UTC

throwoutttt wrote: post #15

GraphQL is far superior for development speed, API flexibility and extensibility, authorisation, discovery, testing, and less bugs.

But not for range of clients

Re: Best practices for REST API design (2020)

#17

Post by BerislavLopac » Mon, Feb 22, 2021, 4:07 PM UTC

ed25519FUUU wrote: post #13

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…

Isn’t 409 if you’re trying to update an existing record (PUT) and not create a new record (POST)? The ambiguity is probably why most people just use 400 and call it a day.

There's this, FWIW: https://i.stack.imgur.com/whhD1.png

Re: Best practices for REST API design (2020)

#18

Post by gmanis » Mon, Feb 22, 2021, 4:12 PM UTC

veesahni wrote: post #2

I've written a comprehensive one on this topic a few years ago: https://www.vinaysahni.com/best-practices-for-a-pragmatic-re...

Thank you for this. It is my go to post every time I implement an api service or even for web development.

Re: Best practices for REST API design (2020)

#19

Post by pugworthy » Mon, Feb 22, 2021, 4:14 PM UTC

A question I’ve always had about 404 and APIs...

How do you distinguish between an invalid path (no end point) and a valid path requesting a resource that doesn’t exist?

Re: Best practices for REST API design (2020)

#20

Post by johnchristopher » Mon, Feb 22, 2021, 4:15 PM UTC

throw_m239339 wrote: post #6

All these "best practices" are exactly why I embraced GraphQL quickly and flushed "REST" down the toilets for big projects (http+json is fine for small ones, since no lib overhead). GraphQL is unashamedly the new SOAP. I.e. we have a spec, not a series of "best practices" thus endless architectural debates where people are shamed for 'doing it the wrong way' online. - Accept and respond with JSON: No, why? what if I…

We need a prettier for REST API.