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

211–220 of 273 posts

Re: Best practices for REST API design (2020)

#211

Post by resonantjacket5 »

motogpjimbo wrote: post #23
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…

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…

interesting, I didn't know using graphQL could help remove so many design debates (compared to rest). But yeah it makes sense since with rest you have to keep thinking about whether or not you'll extend the /foos/{foo_id}/bars/{bar_id}/baz or say put it on its own resource /baz/{baz_id} etc...

maybe I'll investigate graphql a bit more, I've just heard it was really complicated to implement the resolvers for the queries so people weren't using them yet.

Re: Best practices for REST API design (2020)

#212

Post by kaoD »

tshaddox wrote: post #161
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.

The notion of "page" really only applies as an arbitrary interface division to make performance predictable. The same book could be published in different form factors such that there's no real meaning to a specific page number. There's no "turn your bibles to page 112." That's even more clearly true when the data itself is changing over time, such that even the first thing on the first page is changing over time. Th…

Isn't that just pagination with a different granularity?

You'd still present the user with a set of results (a "page") and would let them seek forwards/backwards to the adjacent subsets of results.

AFAICT cursors can't support this.

And even if you go halfways into the list you can't display all subsequent items, so you'd still have to paginate in some way.

The page metaphor is there for a good reason.

Re: Best practices for REST API design (2020)

#213

Post by tomg »

chrisandchris wrote: post #183
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 numbers as string [...] Why? Why not send a number as number (double) and treat it as hostile in the backend? I dislike sending numbers as string because I think the different data types exist for a reason.

A bit off-topic but I received an email from a government agency today that pretty printed my ZIP code as "12,345", I'm assuming because they store ZIP as a number. Made me wonder what would happen if I used a full 9 digit ZIP code with a minus sign.

Re: Best practices for REST API design (2020)

#214

Post by tshaddox »

lyjackal wrote: post #178
crescentfresh wrote: post #176

Earlier quoted context omitted.

> 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"'

Then why add the "in UTC" part? ISO 8601 specifies how to designate the time zone.

Re: Best practices for REST API design (2020)

#215

Post by jshprentz »

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://xkcd.com/1179/

Re: Best practices for REST API design (2020)

#216

Post by tshaddox »

kaoD wrote: post #212
tshaddox wrote: post #161

Earlier quoted context omitted.

The notion of "page" really only applies as an arbitrary interface division to make performance predictable. The same book could be published in different form factors such that there's no real meaning to a specific page number. There's no "turn your bibles to page 112." That's even more clearly true when the data itself is changing over time, such that even the first thing on the first page is changing over time. Th…

Isn't that just pagination with a different granularity? You'd still present the user with a set of results (a "page") and would let them seek forwards/backwards to the adjacent subsets of results. AFAICT cursors can't support this. And even if you go halfways into the list you can't display all subsequent items, so you'd still have to paginate in some way. The page metaphor is there for a good reason.

There are two concepts here. One is simply the idea of a service returning only some portion of the items in a list for each request. That notion almost always exists simply for practical reasons: to bound the performance for retrieving, formatting, transferring, and consuming the list. I have no problem with that.

The other concept is using an actual page number to make requests, e.g. requesting {page: 1} and then subsequently requesting {page: 2}. This concept is the one I was claiming is less desirable than some alternatives.

As for cursors, I don't see any reason why you couldn't make requests like {listPosition: "50%"} or {createdBefore: "2020-02-15"} and then still use cursors in the response to request the previous or next page. (Those two examples probably aren't actually good API naming conventions, but it should demonstrate the idea.)

Re: Best practices for REST API design (2020)

#217

Post by qudat »

NanoWar wrote: post #194
Octoth0rpe wrote: post #56

Earlier quoted context omitted.

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

You could simply use HAL with embedded resources in JSON. Not sure how the client side feels about that though

It's simpler if it's normalized like with JSONAPI, but all of the apps I've worked on use an E(T)L process where the transformation step normalizes the data before saving it to our cache.

Re: Best practices for REST API design (2020)

#218

Post by Kwpolska »

e12e wrote: post #186
chrisandchris wrote: post #183

Earlier quoted context omitted.

> Send numbers as string [...] Why? Why not send a number as number (double) and treat it as hostile in the backend? I dislike sending numbers as string because I think the different data types exist for a reason.

One reason could be that it's easy to think that a "number" is sanely typed, while you almost never want a double - not for quantity, not for price, etc. So you're going to cast to some (big) integer anyway...

In languages with reasonable number types (i.e. not JS), the parsers are typically able to produce integers, or even BigDecimal, out of a JSON number, without going through double.

Re: Best practices for REST API design (2020)

#219

Post by criddell »

n_e wrote: post #94
Octoth0rpe wrote: post #56

Earlier quoted context omitted.

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

> On the flip side, I've never been frustrated by getting too many fields back from an API A pretty common use-case I have is needing to support these three things : - A “big object” list screen (where retrieving the whole objects would make the query return megabytes off data) - A “big object” details screen (where I need the full object) - Programmatically getting many big objects With GraphQL it involves writing o…

> With GraphQL it involves writing one (or two) straightforward queries, while with REST it would require more thought or code.

Aren't you just pushing the work to the back end? The GraphQL resolver is a new layer of complexity while with REST is more straightforward.

Re: Best practices for REST API design (2020)

#220

Post by vageli »

chrisandchris wrote: post #183
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 numbers as string [...] Why? Why not send a number as number (double) and treat it as hostile in the backend? I dislike sending numbers as string because I think the different data types exist for a reason.

Many of the numbers we use day to day are more like strings than actual integers, though. What sense does it make to divide by a zip code, or two add two zip codes together for instance?
Post reply on HN