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

How to Design Better APIs

r.bluethl.net

Post reply on HN
Print view View original

11–20 of 238 posts

Re: How to Design Better APIs

#11

Post by hardwaresofton »

A few things I see rarely discussed that I often do:

- Always use a response envelope

- HTTP status is not the same as your application status. I always include a "status" field in the response envelope (OP recommends standardizing errors but I think standardize all of it)

- Always have an unique error code for every error your API can return (they should also be URL safe ("some-thing-went-wrong"), basically an enum of these should exist somewhere, the more specific the better.

- Offer OpenAPI whenever you can.

- There is no such thing as a publicly exposed "private" API. If it can be hit (and is not protected), it eventually will be.

- Do blackbox testing of your API, E2E tests are the most important kind of test you could have.

- (controversial) build in special test/debug endpoints -- these help with blackbox testing.

Re: How to Design Better APIs

#13

Post by metadat »

hardwaresofton wrote: post #11

A few things I see rarely discussed that I often do: - Always use a response envelope - HTTP status is not the same as your application status. I always include a "status" field in the response envelope (OP recommends standardizing errors but I think standardize all of it) - Always have an unique error code for every error your API can return (they should also be URL safe ("some-thing-went-wrong"), basically an enum…

Are you able to elaborate on what is a response envelope?

Edit:

Nevermind, see [0]. It's the simple and intuitive concept of encasing the payload in an consistently structured object which includes metadata, e.g.

    {"Error": null, Data: ...}
[0] https://stackoverflow.com/questions/9989135/when-in-my-rest-...

Makes intuitive sense, as it's then easier to develop a nice, generic REST client.

Re: How to Design Better APIs

#14

Post by JaggedJax »

pan69 wrote: post #4

Some nice tips in here. However, tip 15, I strongly disagree with: > 15. Allow expanding resources I would suggest the opposite. A REST API should not return nested resources at all. Instead, and to stay with the example provided on the website, to obtain the "orders", the /users/:id/orders endpoint should be called. It might be tempting to return nested resources, because clients would only have to make a single cal…

I've consumed the kinds of APIs you're referencing and they are my least favorite. I would prefer a poorly documented API over one that returns me 15 IDs that I must look up in separate calls. I think there's a reason those APIs also tend to have rate limits that are way too low to be useful.

Re: How to Design Better APIs

#18

Post by jimbob45 »

BulgarianIdiot wrote: post #15

Mostly common-sense things, but I can't wait for the community to stop trying to use PUT, PATCH, DELETE and the like. There's a reason that in 2022 web forms only support GET and POST (and implicitly, HEAD).

Are you saying dump DELETE because you should instead logically delete it with an IsDeleted column passed in via POST?

Re: How to Design Better APIs

#19

Post by djbusby »

jimbob45 wrote: post #18
BulgarianIdiot wrote: post #15

Mostly common-sense things, but I can't wait for the community to stop trying to use PUT, PATCH, DELETE and the like. There's a reason that in 2022 web forms only support GET and POST (and implicitly, HEAD).

Are you saying dump DELETE because you should instead logically delete it with an IsDeleted column passed in via POST?

Or POST to '/resource/id/delete'? That's my least favourite pattern

Re: How to Design Better APIs

#20

Post by boredtofears »

BulgarianIdiot wrote: post #15

Mostly common-sense things, but I can't wait for the community to stop trying to use PUT, PATCH, DELETE and the like. There's a reason that in 2022 web forms only support GET and POST (and implicitly, HEAD).

Huh? There’s full browser support for all of those verbs.

What is the argument for not supporting them?

Post reply on HN