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

171–180 of 273 posts

Re: Best practices for REST API design (2020)

#171

Post by simiones »

mikewhy wrote: post #109
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(…

What would you do if someone wanted: - some fields of the resource - some fields of the comments - some fields of the user that made the comments

It depends on performance requirements. Either ask them to retrieve the entire objects, or expose a new endpoint to retrieve the filtered list in an optimal way.

API consumers definitely aren't the ones who should be thinking about something like joining behavior, since GraphQL doesn't give nearly enough control to achieve performant joining.

Basic filtering can also be easily achieved with ad-hoc methods, such as query params. No need for a full-blown GraphQL language server in front of all your services.

Re: Best practices for REST API design (2020)

#172

Post by simiones »

dnautics wrote: post #141
fc373745 wrote: post #72

Earlier quoted context omitted.

Unfortunately for graphql, the claim that backend teams need to be constantly making endpoints for other decoupled teams is not as drastic and critical as you consider it to be. Dare i even say switching to graphql and onboarding developers to graphql is a much more resource intensive process than adding another endpoint (or a couple).

> onboarding developers to graphql is a much more resource intensive process As a BE/remote I basically taught myself most of elixir's graphQL framework in a day (wait, that was yesterday), while under feature pressure (due this afternoon), mostly by poking around and doing a bit of TDD. There are parts that I really hate about graphQL, but overall I consider it a win.

The problem with GraphQL is on the front end. Suddenly, the FE team becomes responsible for understanding the entire data model, which resources can be joined together, by what keys, and what is actually performant vs what isn't.

Instead of doing a simple GET /a/b/1/c and presenting that data structure, they now need to define a query, think about what resources to pull into that query etc. If the query ends up being slow, they have to understand why and work on more complex changes than simply asking the BE team for a smaller response with a few query params.

Re: Best practices for REST API design (2020)

#173

Post by simiones »

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…

One big disadvantage about GraphQL is that, in a microservices architecture, it requires a fat centralized GraphQL gateway that understands your whole application in order to dispatch queries to other microservices. This is much fatter than a reverse proxy with a few URL-based matching rules, and harder to scale as well.

Re: Best practices for REST API design (2020)

#174

Post by systemvoltage »

adamscybot wrote: post #127
systemvoltage wrote: post #106

Earlier quoted context omitted.

You can create a single endpoint that's non-RESTFul to make a single call.

Yes and by doing so you lost the advantages of a predictable and well organised API. GraphQL has first class support for this scenario.

I disagree. You're shifting your "organization" to the frontend which becomes an utter cesspool of chaos. If anything changes in the backend, you will need to change the frontend as well.

The whole point of an API is to decouple. GraphQL does the exact opposite.

Re: Best practices for REST API design (2020)

#175

Post by dnautics »

simiones wrote: post #172
dnautics wrote: post #141

Earlier quoted context omitted.

> onboarding developers to graphql is a much more resource intensive process As a BE/remote I basically taught myself most of elixir's graphQL framework in a day (wait, that was yesterday), while under feature pressure (due this afternoon), mostly by poking around and doing a bit of TDD. There are parts that I really hate about graphQL, but overall I consider it a win.

The problem with GraphQL is on the front end. Suddenly, the FE team becomes responsible for understanding the entire data model, which resources can be joined together, by what keys, and what is actually performant vs what isn't. Instead of doing a simple GET /a/b/1/c and presenting that data structure, they now need to define a query, think about what resources to pull into that query etc. If the query ends up being…

that's an interesting point! And the graphql basically obscures a mental model over a broad abstraction, so it's impossible to know exactly what's going on without going through and actually reading the BE code itself. Thanks for the perspective.

Re: Best practices for REST API design (2020)

#176

Post by crescentfresh »

ehutch79 wrote: post #165
derkoe wrote: post #159

Most of these best practices forget the hard parts of JSON/REST APIs: - How to handle date and time incl. time zones - JSON has no data type for that - Handling of numbers (JSON only has double, which does not fit most cases) - Defined and parseable error responses (rfc 7807 plus extra fields for details) - Localization - do you send translated texts or just error codes? - How to handle updates? Overwrite every field…

Send ISO date/time in utc. Send numbers as strings. you should be treating this as hostile in your backend anyways, and checking it. Send both an error code, and a string in simple english, or whatever your most common developer language is. If you care about only updating certain fields, track changes and only send those fields to the backend. These arn't really that hard.

> Send ISO date/time in utc

what's an ISO date/time?

Re: Best practices for REST API design (2020)

#177

Post by [deleted] »

crescentfresh wrote: post #176
ehutch79 wrote: post #165

Earlier quoted context omitted.

Send ISO date/time in utc. Send numbers as strings. you should be treating this as hostile in your backend anyways, and checking it. Send both an error code, and a string in simple english, or whatever your most common developer language is. If you care about only updating certain fields, track changes and only send those fields to the backend. These arn't really that hard.

> Send ISO date/time in utc what's an ISO date/time?

[deleted]

Re: Best practices for REST API design (2020)

#178

Post by lyjackal »

crescentfresh wrote: post #176
ehutch79 wrote: post #165

Earlier quoted context omitted.

Send ISO date/time in utc. Send numbers as strings. you should be treating this as hostile in your backend anyways, and checking it. Send both an error code, and a string in simple english, or whatever your most common developer language is. If you care about only updating certain fields, track changes and only send those fields to the backend. These arn't really that hard.

> Send ISO date/time in utc what's an ISO date/time?

I assume GP means ISO8601 Date Time https://en.wikipedia.org/wiki/ISO_8601. Default behavior of javascript date json serialization

  > JSON.stringify(new Date())
  '"2021-02-22T20:34:53.686Z"'

Re: Best practices for REST API design (2020)

#179

Post by ehutch79 »

crescentfresh wrote: post #176
ehutch79 wrote: post #165

Earlier quoted context omitted.

Send ISO date/time in utc. Send numbers as strings. you should be treating this as hostile in your backend anyways, and checking it. Send both an error code, and a string in simple english, or whatever your most common developer language is. If you care about only updating certain fields, track changes and only send those fields to the backend. These arn't really that hard.

> Send ISO date/time in utc what's an ISO date/time?

https://en.wikipedia.org/wiki/ISO_8601

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe...

Re: Best practices for REST API design (2020)

#180

Post by dec0dedab0de »

ngrilly wrote: post #148
dec0dedab0de wrote: post #84

Earlier quoted context omitted.

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

That solves the problem of items added concurrently (by deduplicating them) but that doesn't solve the problem of removed items.

The only thing that completely solves for removed items is constantly polling, or setting up a webhook/callback of some kind.

Padding the offset would solve for the problem mentioned where deleting an item would mean some non deleted items are not included in the paging results because they got moved up a page after that page was requested, but before the next page was requested. For example If I request 100 items at a time but set my offset to be 90 more than what i have received so far, i can expect my response to have duplicates, if it does not then i know my offset was not padded enough and i can request from a different offset. Of course you would adjust the numbers based on knowledge of the data.

Edit: If you used the ID of the last item instead of an offset, then you could get errors if your last item is in fact the one that was deleted.

Post reply on HN