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

241–250 of 273 posts

Re: Best practices for REST API design (2020)

#241

Post by hcarvalhoalves »

mobjack wrote: post #131

Using HTTP methods as verbs is a terrible practice. It works for simple CRUD APIs, but it becomes too limiting once there are more than one way of updating something. It ties the API design too closely to the data model and usually means that the client has to implement more business logic instead of handling that on the server. Good API design should decouple business logic from the HTTP spec.

You don’t need more than the HTTP methods as long as you reify requests as resources.

Instead of “doSomeAction on resource” it’s “POST/PUT /resource/actionRequest”.

The trick is stopping and trying to make everything work over CRUD of your main entity resources. HTTP resources don’t need to map to tables.

Re: Best practices for REST API design (2020)

#242

Post by quesera »

bickeringyokel wrote: post #155
motogpjimbo wrote: post #92

Earlier quoted context omitted.

To continue the payment processor example, if there are 10 different reasons for declining a transaction, how do you propose mapping those onto 4xx codes? Would you just choose 10 at random? Or would you just return, e.g., E_INSUFFICIENT_FUNDS?

I'm not sure anyone would propose you randomly map different 4xx codes to a bunch of different internal server errors. For the one example you provided I would probably use a 500 code, return the relevant message and call it a day. In that case you might also return an additional code if you have some extremely complex logic for handling that error at the client side, but in that case your client might be a little to…

FWIW, my policy is that 5xx codes are always bugs, or an infrastructure-level failure/refusal to serve.

4xx codes are processing errors, or application-level refusals.

I end up borrowing 422 from WebDAV for a generic "Unprocessable Entity", with an error code (for API interpretation/reference lookup) and description (for user display, when appropriate) in the response body.

Re: Best practices for REST API design (2020)

#243

Post by rsj_hn »

By far the most important best practice is to keep the damn thing stable and online. I'd much rather integrate an API that doesn't change but maybe has a few pain points in developing the client than one where the client is a bit easier to develop but the API changes every year.

Re: Best practices for REST API design (2020)

#244

Post by rsj_hn »

pugworthy wrote: post #143
mariusor wrote: post #26

Earlier quoted context omitted.

If doesn't exist means it has been removed: 410 Gone, if doesn't exist means not yet created: 404 Not Found. I can't think for other types of not existing, or why you'd need to differentiate between them.

Say I have an API with a path of /customer/ . I call /customer/235235 and customer 235235 doesn't exist. That's a 404, resource not found. But say I make an uncaught error with the path and call /cutsomer/235235. That also is a 404, resource not found. It really depends on what you want the word "resource" to mean. It gets a bit more complex if you have a simplistic website with an API service both on the same server…

> It really depends on what you want the word "resource" to mean.

I once worked with an old API and when a pentest team ran a scanner against it they reported hundreds of backdoors and malicious code false positives because they were expecting a 400 error rather than an 200 with success=false response body

Re: Best practices for REST API design (2020)

#245

Post by rsyring »

adolph wrote: post #239
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. 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.

Re: Best practices for REST API design (2020)

#246

Post by spelunker »

capableweb wrote: post #87
spelunker wrote: post #81

Earlier quoted context omitted.

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

Thanks, I'm a programmer professionally, and I broadly understand HTTP and the language of the web. Talking down to me is really helpful though.

It's true, I don't know erlang, or mochiweb, or the nitty-gritty of content negotiation, but OP presented this library as an alternative to "accept and respond with JSON" so I attempted to read the readme because I was curious. And then quickly lost my curiosity when I again, had no idea what this library actually did. If a readme is meant to be an inviting and basic overview of what a library does and why I should use it, the readme failed.

Re: Best practices for REST API design (2020)

#247

Post by bickeringyokel »

quesera wrote: post #242
bickeringyokel wrote: post #155

Earlier quoted context omitted.

I'm not sure anyone would propose you randomly map different 4xx codes to a bunch of different internal server errors. For the one example you provided I would probably use a 500 code, return the relevant message and call it a day. In that case you might also return an additional code if you have some extremely complex logic for handling that error at the client side, but in that case your client might be a little to…

FWIW, my policy is that 5xx codes are always bugs, or an infrastructure-level failure/refusal to serve. 4xx codes are processing errors, or application-level refusals. I end up borrowing 422 from WebDAV for a generic "Unprocessable Entity", with an error code (for API interpretation/reference lookup) and description (for user display, when appropriate) in the response body.

Yeah that's understandable when frameworks default everything to 500, that's often true, I just couldn't think of a more appropriate code to the specific example apparently there actually is a code for fraudulent payments so 402 code would be good.

Re: Best practices for REST API design (2020)

#248

Post by bickeringyokel »

hallman76 wrote: post #204
bickeringyokel wrote: post #155

Earlier quoted context omitted.

I'm not sure anyone would propose you randomly map different 4xx codes to a bunch of different internal server errors. For the one example you provided I would probably use a 500 code, return the relevant message and call it a day. In that case you might also return an additional code if you have some extremely complex logic for handling that error at the client side, but in that case your client might be a little to…

re: best practices. I inherited an API that always responds with 200s, even when there's an error condition. When a document can't be found it returns a 200 OK with a response body "NOT_FOUND". By ignoring existing standards and re-inventing the wheel with custom errors the previous development team made the system harder to maintain & harder to onboard.

I've also encountered that, it's very frustrating when you get a 200 ok, then you continue on in your client but there was actually an error expressed in the body of the 200 response. Ah gee.

Re: Best practices for REST API design (2020)

#249

Post by nojvek »

criddell wrote: post #219
n_e wrote: post #94

Earlier quoted context omitted.

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

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

Re: Best practices for REST API design (2020)

#250

Post by rualca »

incrudible wrote: post #164
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…

> 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 that your experience is slim to none in this domain so that you are not mindful of the most basic challenges of getting servers and clients that evolve independently to continue to interoperate with minimal development effort. REST is content discovery and allowing clients to transparently adapt to breaking changes in the server. How does anyone with any relevant experience miss the point of that?

Furthermore, your assertion makes no sense at all. The main property, and the whole point, of REST is HATEOAS. It makes absolutely no sense to claim an API is REST if it misses the single most important design element that's behind REST. This is not pedantry or nit-picking: it's the whole difference between plain old RPC and REST. If you want to design an API that provides fixed endpoints to be called,and isn't discoverable or navigable, then just call the spade a spade: RPC over HTTP. Otherwise why do you feel the need to claim you design an API around a design principle you don't use and even criticize?

Post reply on HN