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

181–190 of 238 posts

Re: How to Design Better APIs

#181

Post by asadawadia »

kumarvvr wrote: post #37

Sometimes, I feel that we ought to have a simple protocol, on top of HTTP, to simply do remote procedure calls and throw out all this HTTP verbs crap. Every request is a http POST, with or without any body and the data transfer is in binary. So that objects can be passed back and forth between client and server. Sure, there is gRPC, but it requires another API specification (the proto files). There I said it. HTTP Ve…

>Sometimes, I feel that we ought to have a simple protocol, on top of HTTP, to simply do remote procedure calls and throw out all this HTTP verbs crap. Every request is a http POST, with or without any body and the data transfer is in binary. So that objects can be passed back and forth between client and server.

https://github.com/asad-awadia/indie-rpc

Re: How to Design Better APIs

#182

Post by smoyer »

pokoleo wrote: post #2

The error messages could be better yet. The example uses a different code per issue, for instance: "user/email_required". Most integrators will build their UI to highlight the input fields that contain an error. Making them parse the `code` field (or special-case each possible code) is pretty toilsome. // from blog post { "code": "user/email_required", "message": "The parameter [email] is required." } Make it parseab…

It also doesn't hurt to repeat the HTTP status code in the JSON body - when you receive a response, the status code and entity body are coupled but even if the server logs the status code, they're often decoupled in the logging system - having both in one log entry is way easier!

Re: How to Design Better APIs

#183

Post by [deleted] »

kortex wrote: post #178
hardwaresofton wrote: post #53

Earlier quoted context omitted.

Well I imagine this is why sages like uncle bob and sam newman will always be needed. > Validation errors are errors and network failures are errors, but they’re very different animals and should never be conflated. > I don’t want to check for a status code in metadata ever, when an HTTP status is provided. These seem like conflicting views. If the HTTP status is all you check you must be conflating application/opera…

I think I'm with Jack on this one, at least when it comes to REST interfaces. When I query GET /bar/123, I want an object with a Bar protocol/content-type. I don't want a Envelope[Bar]. What if it's any data type other than json-isomorphic, e.g. image or video? Is /videos/123.mp4 going to return a json object like {"data": , "status": "whatever"} Of course not! You already have an envelope, it's the HTTP protocol. Th…

[deleted]

Re: How to Design Better APIs

#184

Post by bmn__ »

wokwokwok wrote: post #29

I’m gonna say it: Many rest apis are lazy and developer friendly, not consumer friendly. If you have related resources, let’s say, product and product options as two distinct endpoints: - /api/product - /api/options Then, and I want to be clear here, it is impossible for a client to perform an atomic operation on multiple distinct objects types. Let’s say the client needs to add a product with a single option or fail…

> it is impossible for a client to perform an atomic operation on multiple distinct objects types.

> It doesn’t meet the “standard” for a rest api? Too bad.

It is perfectly fine to model the creation of a product with options via a new resource. Another possibility is to model this as a transaction, a series of requests. Both meet the goals of atomicity and also following restful constraints.

But since you disallowed those possibilities as the premise, there is no constructive way forward from there. Nice construction of a straw-man, must feel satisfying to see it topple over, but who do you hope to impress with that?

Re: How to Design Better APIs

#185

Post by [deleted] »

Supermancho wrote: post #57
BulgarianIdiot wrote: post #30

Earlier quoted context omitted.

Based on that description, you may be using PUT in conflict with its semantics (namely, idempotent way to replace an entire resource). This is one reason why I don't bother with these methods and stick to GET and POST.

> I don't bother with these methods and stick to GET and POST. Most people don't bother with them. If you need caching or want to be able to manipulate params in the browser/link to resources, use GET. This idea that you need additional verbs for web services is a classic case of in-theory vs in-practice. Introducing non-trivial complication for very tiny benefit is a strange tradeoff.

[deleted]

Re: How to Design Better APIs

#186

Post by bcrosby95 »

BulgarianIdiot wrote: post #30
polishdude20 wrote: post #26

We don't use PATCH but use a PUT for partial objects. We have validator code at every endpoint and we validate both creates and updates. When a PUT comes in, the validator knows what can and can't be changed. Depending on your role, the validator lets you change certain things can be updated as well. A PATCH would need these too and now you have more code to deal with. Also, it requires the developer to now worry tha…

Based on that description, you may be using PUT in conflict with its semantics (namely, idempotent way to replace an entire resource). This is one reason why I don't bother with these methods and stick to GET and POST.

PUT can be useful if you have a client that tries to handle errors. For example, our mobile application will automatically retry a PUT.

Re: How to Design Better APIs

#187

Post by [deleted] »

kortex wrote: post #178
hardwaresofton wrote: post #53

Earlier quoted context omitted.

Well I imagine this is why sages like uncle bob and sam newman will always be needed. > Validation errors are errors and network failures are errors, but they’re very different animals and should never be conflated. > I don’t want to check for a status code in metadata ever, when an HTTP status is provided. These seem like conflicting views. If the HTTP status is all you check you must be conflating application/opera…

I think I'm with Jack on this one, at least when it comes to REST interfaces. When I query GET /bar/123, I want an object with a Bar protocol/content-type. I don't want a Envelope[Bar]. What if it's any data type other than json-isomorphic, e.g. image or video? Is /videos/123.mp4 going to return a json object like {"data": , "status": "whatever"} Of course not! You already have an envelope, it's the HTTP protocol. Th…

[deleted]

Re: How to Design Better APIs

#188

Post by mobjack »

FearlessNebula wrote: post #177
kumarvvr wrote: post #37

Sometimes, I feel that we ought to have a simple protocol, on top of HTTP, to simply do remote procedure calls and throw out all this HTTP verbs crap. Every request is a http POST, with or without any body and the data transfer is in binary. So that objects can be passed back and forth between client and server. Sure, there is gRPC, but it requires another API specification (the proto files). There I said it. HTTP Ve…

I’m not sure what issue the verbs are creating, can someone help me get through my thick skull what this persons issue with them is? I don’t see how they add much complexity, just check the API docs and see what verb you need to use to perform a certain action.

They are the wrong layer of abstraction outside of simple CRUD apps.

If you have to check the API docs anyways, I rather define custom domain specific verbs than debate whether something should be a PUT or a PATCH.

Re: How to Design Better APIs

#189

Post by scurvy_steve »

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…

- Always use a response envelope

I would mostly agree except in 1 case, streaming data is easier without an envelope. Making some array inside an envelope stream is usually more code and messier than just getting some metadata out of header. So if you have something like data integration endpoints and you expect someone could pull many megs of records, consider no envelope.

Re: How to Design Better APIs

#190

Post by djbusby »

worik wrote: post #108
djbusby wrote: post #21

Earlier quoted context omitted.

8601 has a large pattern space - RFC 3339 is a narrower subset of ISO. Somewhere I saw a diagram that convinced me. I link if I can find again. Edit: a relevant link https://news.ycombinator.com/item?id=28976526

https://ijmacd.github.io/rfc3339-iso8601/ A ven diagram very cool

That's the one! Thanks!
Post reply on HN