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

Re: Best practices for REST API design (2020)

#51

Post by trevor-e » Mon, Feb 22, 2021, 4:43 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…

I've read through the README and links and still have no idea what webmachine does.

Re: Best practices for REST API design (2020)

#52

Post by packetlost » Mon, Feb 22, 2021, 4:44 PM UTC

dnautics wrote: post #39

idlewords wrote: post #34

Earlier quoted context omitted.

I'd recommend the opposite, as with a versioned URL you can very easily route stuff to different machines by simple URL inspection and have a very clean separation between versions.

Unless you're talking about a human dispatching the request (url toolbar or via tool like curl) There's nothing special between a url path or a content header Either way it's layer 7 routing. What was the advantage again?

Load balancers/reverse proxy have first-class support for routing based on paths, but support for routing based on headers is trickier or not possible depending on the software.

Re: Best practices for REST API design (2020)

#53

Post by switch007 » Mon, Feb 22, 2021, 4:44 PM UTC

haidrali wrote: post #31

I always found this document by Microsoft very very good https://docs.microsoft.com/en-us/azure/architecture/best-pra...

If only some teams at Microsoft would read that. Man some of their APIs are annoying

Re: Best practices for REST API design (2020)

#54

Post by motogpjimbo » Mon, Feb 22, 2021, 4:48 PM UTC

mariusor wrote: post #38

motogpjimbo wrote: post #23

Earlier quoted context omitted.

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…

> No user cares whether an error response came back with a 400 or a 409 status Unless your product is itself an API, your users shouldn't be exposed to its status codes. Sorry for dispensing trite advice, but you should really have a nice client between API and users, that can translate the difference between 400 and 409 statuses in a comprehensible and friendly way. :)

That's the purpose of an error message isn't it? I'm not sure what an HTTP response code is adding to that.

In my experience, in any situation where you produce an API where you want the client to pay close attention to the actual error that occurred, the list of official HTTP response codes is generally woefully inadequate for the task and you're going to want to work with something much more specific.

If my payment processor is telling me they're declining a transaction because the customer failed a fraud check, I'd rather they didn't communicate that to me with some random 4xx code one of their devs found on a Wikipedia article and tried to bend into shape. Rather, I'd hope the importance of the situation would lead them to compile a table of custom error codes that I can implement properly in my program's logic.

Re: Best practices for REST API design (2020)

#55

Post by llimllib » Mon, Feb 22, 2021, 4:48 PM UTC

mhoad wrote: post #25

Just for a point of reference here is Google’s take on the exact same topic. It has a bit more of a gRPC background but still is very REST friendly by default. https://cloud.google.com/apis/design/resources Also as one of the most common pushbacks people have with gRPC is that everyone generally expects JSON still in 2021 especially in the browser. Not sure if this is super well known or not but gRPC integrates well…

I had really good success with https://github.com/grpc-ecosystem/grpc-gateway for returning json to the web from a grpc system

Re: Best practices for REST API design (2020)

#56

Post by Octoth0rpe » Mon, Feb 22, 2021, 4:48 PM UTC

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 a non-issue to solve/talk about in almost every other context.

Re: Best practices for REST API design (2020)

#57

Post by mhoad » Mon, Feb 22, 2021, 4:49 PM UTC

packetlost wrote: post #49

mhoad wrote: post #25

Just for a point of reference here is Google’s take on the exact same topic. It has a bit more of a gRPC background but still is very REST friendly by default. https://cloud.google.com/apis/design/resources Also as one of the most common pushbacks people have with gRPC is that everyone generally expects JSON still in 2021 especially in the browser. Not sure if this is super well known or not but gRPC integrates well…

gRPC is also a 300lb gorilla of a framework for communication and has huge problems with versioning if you aren't "running at HEAD".

My original comment might have given the impression that I was some gRPC guru when in reality I’ve only played with it very briefly.

What are the versioning problems with it? I was under the impression that it was actually designed from the start to be fairly flexible with regards to changing API methods etc

Re: Best practices for REST API design (2020)

#58

Post by dliff » Mon, Feb 22, 2021, 4:50 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've gone back and forth on this in respect to database tables and ultimately prefer singular. If the table is named "profile", I think it's obvious that it can store more than 1 profile, since... well it's a table and has rows.

Re: Best practices for REST API design (2020)

#59

Post by fc373745 » Mon, Feb 22, 2021, 4:50 PM UTC

dnautics wrote: post #45

fc373745 wrote: post #36

Earlier quoted context omitted.

like i said, specify what you want in the query params or in the request body

So, what you are saying is reimplement graphQL.

no, what im saying is graphql is introducing something they think is novel, when it already can be done in REST.

it's not hard.

In my specific case, using Flask-Marshmallow i can do this

```

    some_resource = Resource.find_by_id(resource_id)

    arg = request.args.get('type_of_resource')

    if arg == 'with_commments':

        return full_resource_schema.dump(some_resource), 200

    if arg == 'no_comments':

        return no_comments_schema.dump(some_resource), 200

```

there i just implemented graphql in 6 lines of code

Re: Best practices for REST API design (2020)

#60

Post by pkulak » Mon, Feb 22, 2021, 4:52 PM UTC

agentultra wrote: post #24

I'd recommend against using `v1` in the path and prefer content negotiation: GET /resource/1 Accept-Version: ~1.0.2 ... Implementation-wise this ends up with better code (and less code) on the back-end and a reduced number of HTTP routes (which should represent the entities and be maintained). The pain of REST is that there's very little in terms of "correct" as we don't have a formal specification of the semantics.…

I dunno. We started doing something like that at my company (we actually use the plain Accept/Content-Type headers, so "application/vnd.mycompany.service.v1+json") and it's been a giant pain. Routing based on headers sounds cool, but basically no backend OR frontend frameworks support it well. Even if they say they support, there are bugs or weird traps to fall into. Path versioning is just so much easier for everyone.