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

Best practices for REST API design (2020)

stackoverflow.blog

Post reply on HN
Print view View original

81–90 of 273 posts

Re: Best practices for REST API design (2020)

#81

Post by spelunker »

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…

> 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.

Re: Best practices for REST API design (2020)

#82

Post by masklinn »

kaoD wrote: post #71
ngrilly wrote: post #65

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.

As a user I expect that to happen. Cursors on the other hand are awful for getting to arbitrary pages, they are mostly useful for "More" links as on HN or Reddit. It's a trade-off.

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.

Re: Best practices for REST API design (2020)

#83

Post by fc373745 »

dnautics wrote: post #64
fc373745 wrote: post #59

Earlier quoted context omitted.

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.

also, to add another point.

Most API teams will give you all the resources that you need.

It is most likely the case that the FE team will ask not for more, but rather, for less.

This was the exact problem why GraphQl was created in the first place - to account for Facebook's mobile platform, because they were receiving way too much data that needed to be trimmed because they didn't want to be sending like 500kb of json over mobile networks.

Competent API teams will give you all the resources that you need to be productive as a FE engineer, and if it is the case that your data needs some trimming, then go ahead and ask your decoupled backend team, while you can go ahead and keep working asynchronously while they get that done for you.

Not Fatal as you think it is.

Re: Best practices for REST API design (2020)

#84

Post by dec0dedab0de »

ngrilly wrote: post #65

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.

i prefer an offset, then a crawling client can pad their requests and remove anything with a duplicate id.

Re: Best practices for REST API design (2020)

#85

Post by matt-attack »

masklinn wrote: post #82
kaoD wrote: post #71

Earlier quoted context omitted.

As a user I expect that to happen. Cursors on the other hand are awful for getting to arbitrary pages, they are mostly useful for "More" links as on HN or Reddit. It's a trade-off.

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.

Well good luck giving your users direct page access when your API only supports cursors.

Re: Best practices for REST API design (2020)

#86

Post by dec0dedab0de »

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…

I like having the option to select fields as an optimization, but the main reason i dont like graphql is because it forces me to select fields from the beginning. Most of the time I dont know what the fields are until i look at the data in context. In general, I dont like anything that forces me to rely on documentation.

Re: Best practices for REST API design (2020)

#87

Post by capableweb »

spelunker wrote: post #81
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…

> 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 sentence immediately becomes clear, what Webmachine is aiming for.

I think this happens quite often when you're dealing with a lot of domains you don't understand. I'm not a doctor, so when doctors talk, it can sound like mumbo-jumbo, but I'm sure it makes sense for them, since they are professionals.

Re: Best practices for REST API design (2020)

#88

Post by profquail »

ngrilly wrote: post #65

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.

You can also use SQL:2011 "System-Version Tables" (a.k.a. temporal databases) supported in most of the major RDBMSs now. You'd just need to keep track of a timestamp when you started querying/paginating and include it as part of the SQL query, which'll give clients a consistent view even if the database is being concurrently modified.

Re: Best practices for REST API design (2020)

#90

Post by schnable »

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…

This can really screw up your cache hit ratio.
Post reply on HN