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

261–270 of 273 posts

Re: Best practices for REST API design (2020)

#261

Post by rileymat2 »

rsyring wrote: post #245
adolph wrote: post #239

Earlier quoted context omitted.

>Send ISO date/time in utc. With offset, ok. As UTC alone, it doesn't work if you need to know the local time when something occurred, like medication administration, especially when the things may occur across time changes like DST.

Do not just track offset. If you have to deal with date/time locally, you must have the timezone. Treat this just like bytes/Unicode: accept local time on the edges of the app, convert immediately to UTC, store/use UTC internally, convert back to local on the edges at display time. Yes, it can get more complicated than this of doing calendar math, but I'm not aware of anything gained by just tracking offset.

That does not work in the op’s use case because the op wants to know the local time of the medication administration.

The endpoint of the viewer may not be in the same local time.

If you go this route you may not care about location beyond this one data point, but have to store another location field each time.

Re: Best practices for REST API design (2020)

#262

Post by criddell »

nojvek wrote: post #249
criddell wrote: post #219

Earlier quoted context omitted.

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

Yes, but you don’t have that many network round trips.

Maybe, maybe not.

If there is some sequence that is used a lot and you've determined it to be a bottleneck, you can write a custom endpoint for it.

Re: Best practices for REST API design (2020)

#263

Post by Alex3917 »

chrisandchris wrote: post #258
Alex3917 wrote: post #235

Earlier quoted context omitted.

This. Just because something contains numbers doesn't mean that it's numeric. Times aren't numbers because 6pm * 7am doesn't yield a meaningful result. Same thing with serial numbers, VIN numbers, building floor numbers, phone numbers, etc. All of those should always be strings, because performing "math" on them wouldn't yield meaningful results.

While I basically agree, there‘s a difference between „always send numbers as string“ and „send something that looks like a number but is actually a string as a string“. Why should i send a dimension as a string? How am I going to calculate the volume from 3 strings?

> Why should i send a dimension as a string?

You shouldn't because a dimension is a number. Something 4 feet long is twice as long as something 2 feet long.

Re: Best practices for REST API design (2020)

#264

Post by incrudible »

rualca wrote: post #250
incrudible wrote: post #164

Earlier quoted context omitted.

> This article doesn't mention linking at all, which is at the heart of REST. Please, just don't do it . Yes, I read the dissertation. It's just not a good idea, it has never given me any practical use whatsoever and has always made dealing with the API more annoying. > Most of it is just standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries. Yes, and we call that REST or RESTful a…

> Please, just don't do it. Yes, I read the dissertation. It's just not a good idea, it has never given me any practical use whatsoever and has always made dealing with the API more annoying. If you believe REST is not a good idea then you never had to deal with versioning and struggling to keep clients and servers you don't own to play nice. Asserting that something like REST has no practical purpose is asserting th…

I'm totally fine with calling it RPC-over-HTTP, or RESTless, or unREST. I'm also fine with just calling it REST. I don't care.

I'm not fine with making an API use HATEOAS, especially not for the sake of being pedantically accurate about the word REST.

As for your defense of HATEOAS, you're not doing a good job. If it's such a good idea, why is pretty much nobody doing it as intended? How exactly does it help with versioning? Can you describe a real use case?

The way I see it, if you want to break your API, slap /v2 in front of it. Otherwise, I strongly suggest that you do not break your API. Do not move stuff around pointlessly. I guarantee you that even if you followed HATEOAS best practices to the letter, your clients are still going to break. You don't want that.

Re: Best practices for REST API design (2020)

#265

Post by dragonwriter »

dmitriid wrote: post #226
icod wrote: post #222

Earlier quoted context omitted.

Totally agree. HATEOAS is a PITA. Never overcomplicate things. Never add metadata if you don't have to. Just K.I.S.S

The main problem with REST is that it never developed tools even on the level with what we have for GraphQL. Somehow everyone rushed to implement GraphQL schemas, and no one rushed to implement JSON Schemas for example. And JSON Schemas with the right tools are a much more powerful instrument. Same goes for linking, and the rest of HATEOAS. At a company I worked we had an internal tool built for most of this stuff wh…

> The main problem with REST is that it never developed tools even on the level with what we have for GraphQL.

REST isn't really designed for the problem of implementing a single, centrally controlled API, and is basically overkill for that. Its made for a decentralized, heterogenous network of resources controlled by different parties, which can have separately evolving relationships. Like, say, the WWW.

If you have sufficient tooling around it to consume that kind of heterogenous resource network, it's trivial to apply it to a centralized service, but we don't really have the kind of client tooling for applications other than UIs that makes that nice widely available yet, and everyone wanting walled silos instead of free remixing means that REST is probably an antifeature for lots of API providers even if the tooling was 100% there.

Re: Best practices for REST API design (2020)

#266

Post by dragonwriter »

Longwelwind wrote: post #255
rualca wrote: post #250

Earlier quoted context omitted.

> Please, just don't do it. Yes, I read the dissertation. It's just not a good idea, it has never given me any practical use whatsoever and has always made dealing with the API more annoying. If you believe REST is not a good idea then you never had to deal with versioning and struggling to keep clients and servers you don't own to play nice. Asserting that something like REST has no practical purpose is asserting th…

>If you believe REST is not a good idea then you never had to deal with versioning and struggling to keep clients and servers you don't own to play nice. Sincere question: how does HATEOAS helps with this? The only thing that HATEOAS helps with, is when the URL pointing to an entity changes, which is the most simplest change someone can make to its API. But if an API ever changes the relationships between entities (n…

> Sincere question: how does HATEOAS helps with this?

HATEOAS basically involves two main things:

1. Resource representation specifications are communicated in the communication channel (in HTTP, this can be a combination of MIME type in headers are more specific specification in the document itself for responses, and accepts header in requests.)

2. Related resources are identified by URL.

> The only thing that HATEOAS helps with, is when the URL pointing to an entity changes

False, though #2 helps with that.

> But if an API ever changes the relationships between entities (new entities, 1-1 relationship changed to a 1-m relationship, ...) then HATEOAS won't help at all.

No, that's what #1 helps with, as it provides the means where you can:

(1) identify the resource representations available,

(2) identify if you have a resource-consumption/creation-client available that satisfies the endpoint requirements, and

(3) select the correct client implementation.

> You'll still need to change the logic of your client to take into account the modifications.

Yes, someone needs to implement a new resource client if a new resource structure, or representation of the same structure, is developed.

And if you are doing a single, centralized API, where no one else will be hosting something using the same resources, REST doesn't provide much. Where REST shines (which is why it is abundantly used on the web) is where large numbers of different parties will be hosting services using a potentially shared set of resource representations, where each hosts may evolve the particular set in use on their own schedule, and perhaps even using different network protocols, and you don't want to have bespoke clients for each service, but instead protocol clients for each network protocol and resource clients for each resource representation, and in-band signalling of not only where to get each resource once you get to an entry point, but also have the network protocol client you need and the resource client you need to successfully carry out each transaction.

Re: Best practices for REST API design (2020)

#267

Post by slimbods »

NanoWar wrote: post #191
dec0dedab0de wrote: post #91

Earlier quoted context omitted.

Django REST Framework has this built in, and is very easy to turn on. I always turn it on even though my users almost exclusively use json. I had one user use xml once, because they didnt know how to use json in whatever it was they were using. Noone has ever used yaml, but i leave it there just in case. if you do it right, using the standard html content type returns a human browseable representation of your api wit…

Omg I love the browsable api of Django. I am searching for something similar for .NET - any pointers anyone?

https://swagger.io/tools/swagger-ui/ :)

Re: Best practices for REST API design (2020)

#268

Post by slimbods »

struct wrote: post #3

I’ve also found the Microsoft API guidelines helpful (especially for error handling). https://github.com/microsoft/api-guidelines/blob/vNext/Guide...

Nice reference, but like the OP article, it really goes light on security. I feel that's the hardest part of getting an API released.

Re: Best practices for REST API design (2020)

#269

Post by dmitriid »

dragonwriter wrote: post #265
dmitriid wrote: post #226

Earlier quoted context omitted.

The main problem with REST is that it never developed tools even on the level with what we have for GraphQL. Somehow everyone rushed to implement GraphQL schemas, and no one rushed to implement JSON Schemas for example. And JSON Schemas with the right tools are a much more powerful instrument. Same goes for linking, and the rest of HATEOAS. At a company I worked we had an internal tool built for most of this stuff wh…

> The main problem with REST is that it never developed tools even on the level with what we have for GraphQL. REST isn't really designed for the problem of implementing a single, centrally controlled API, and is basically overkill for that. Its made for a decentralized, heterogenous network of resources controlled by different parties, which can have separately evolving relationships. Like, say, the WWW. If you have…

Very eloquently put! Thank you!

Re: Best practices for REST API design (2020)

#270

Post by Lavinski »

saila wrote: post #133

This article doesn't mention linking at all, which is at the heart of REST. Without links, it isn't REST , and most of the suggestions don't have anything to do with REST per se . Most of it is just standard JSON-over-HTTP stuff that's implemented in a variety of frameworks and libraries. EDIT: To be clear, I don't particularly care if an API is "RESTful" or not, as long as it's well-designed and documented, but I th…

I wrote about why linking is useful recently https://www.daniellittle.dev/practical-hypermedia-controls. I've been using Hypermedia in my APIs for a few years now and it's been so useful for making great APIs. One of the things I really love about it is that you can test/use the API directly much more easily, because the knowledge about how to use it is in the API itself, instead of half hardcoded into the client.
Post reply on HN