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

Re: Best practices for REST API design (2020)

#61

Post by lukeramsden » Mon, Feb 22, 2021, 4:52 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…

It's likely more of an issue if you're wanting to fetch lots of nested data in one request, but only a few specific fields of what could be an extremely large object, like say the just the names and profile picture URIs for a large set of users that have interacted with the object your fetching. This is particularly relevant to social media, such as Facebook.

Re: Best practices for REST API design (2020)

#62

Post by adamrt » Mon, Feb 22, 2021, 4:52 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.

Agree. I've always preferred the Django vs the Rails way on this. Django uses pluralization only for display purposes.

Things are object_detail (singular) and object_list (plural).

It just assumes 'append s' for plural displays, unless you override. I like the _list suffix instead of trying to pluralize

Re: Best practices for REST API design (2020)

#63

Post by jayd16 » Mon, Feb 22, 2021, 4:53 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…

You can do it with query params. Its not enforced or consistent because not everything that serves data can parse the data.

You could throw static json blobs on S3 as a rest API but selections would not be supported.

Re: Best practices for REST API design (2020)

#64

Post by dnautics » Mon, Feb 22, 2021, 4:53 PM UTC

fc373745 wrote: post #59

dnautics wrote: post #45

Earlier quoted context omitted.

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(…

The whole point of graphQL is to allow FE teams to decide what information they need in an organizationally decoupled fashion, you haven't done that at all. Suppose FE wants another join on that object, now they must wait for you to push more code enabling those queries.

Re: Best practices for REST API design (2020)

#65

Post by ngrilly » Mon, Feb 22, 2021, 4:54 PM UTC

Do not use a page argument for pagination. If you have another process/client concurrently adding/removing items, then some items will be returned twice, and others will never be returned. It is better to use, for example, the ID of the last returned item as a starting point for the next query.

Re: Best practices for REST API design (2020)

#66

Post by hardwaresofton » Mon, Feb 22, 2021, 4:54 PM UTC

If you want a pretty decent REST-ish API right out of the box, and you already have a DB, check out PostgREST[0]. More features than you can shake a stick at, and all you have to do is maintain your DB schema.

[0]: https://postgrest.org/en/v7.0.0/

Re: Best practices for REST API design (2020)

#67

Post by [deleted] » Mon, Feb 22, 2021, 4:59 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…

[deleted]

Re: Best practices for REST API design (2020)

#68

Post by Mordisquitos » Mon, Feb 22, 2021, 5:00 PM UTC

throwoutttt wrote: post #46

Mordisquitos wrote: post #40

Small typo-ish error in the article, emphasis mine: > 401 Unauthorized – This means the user isn’t not authorized to access a resource. Surely that should say that the user isn't not unauthorised?

403 is unauthorized (forbidden due to authorization policy). 401 is unauthenticated (not logged in). Very important difference for clients handling authentication state.

That is not false, I didn't not fail to notice that after fixating on the incorrect double negative! However, not to be unfair, 401 is unfortunately not named "unauthenticated", even though it's conventional usage (as you point out) is not unintended to actually mean lack of authentication rather than of authorisation.

Re: Best practices for REST API design (2020)

#69

Post by bigmattystyles » Mon, Feb 22, 2021, 5:02 PM UTC

A bit of an aside, when it comes to querying against a data store, I’ve always wondered why odata is not more popular. In my mind, it’s wonderful.

Re: Best practices for REST API design (2020)

#70

Post by n_e » Mon, Feb 22, 2021, 5:02 PM UTC

fc373745 wrote: post #59

dnautics wrote: post #45

Earlier quoted context omitted.

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(…

Unless I’m missing something, the response schema will have an optional “comments” field whether the “with_comments” arg is passed or not.