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

51–60 of 238 posts

Re: How to Design Better APIs

#51

Post by shoo »

underwater wrote: post #47
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…

Generally internal APIs are developed alongside one or two apps. They don't need a pure, resource-oriented, API that perfectly represents the domain models but ignores how the API is used in practice. A good example is the tip on PUT vs PATCH to update objects. That seems to be missing the point. Why are you forcing the clients to calculate the correct resource fields to PATCH to the server? This is supposed to be an…

structured programming and rpc demonstrates you can get pretty far if your only verb is CALL

Re: How to Design Better APIs

#52

Post by zja »

spikej wrote: post #44
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 don't think I've ever come across any third party actually implementing HATEOAS ( https://en.wikipedia.org/wiki/HATEOAS )

That’s because no one knows what it is.

Re: How to Design Better APIs

#53

Post by hardwaresofton »

JackFr wrote: post #45
hardwaresofton wrote: post #32

Earlier quoted context omitted.

Here's an example straight from code I've rewritten at least 5 times because I'm allergic to saving myself time: export enum ErrorCode { InvalidEntity = 1, NotSupported = 2, UnexpectedServerError = 3, InvalidRequest = 4, Validation = 5, // ... } export enum ResponseStatus { Success = "success", Error = "error", } export class ResponseEnvelope { public readonly status: ResponseStatus = ResponseStatus.Success; public r…

I completely disagree. I find envelopes to be unnecessary cruft that just junk up otherwise clear code. And I think packing metadata into an envelope along with the actual data keeps people from thinking clearly about their own APIs, mostly with respect to ambiguity surrounding the word “error”. Validation errors are errors and network failures are errors, but they’re very different animals and should never be confla…

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/operation status and network status.

> I don’t want to read a time stamp if that time stamp is simply a property of the request. However if the time stamp is a property of the data, then I care - but then it shouldn’t be part of the metadata.

Sure -- I'd like to say that I think the disagreement here boils down to this question: should metadata be represented in data responses.

Correct me if I'm reading you incorrectly, but it seems like you're arguing that metadata should not be represented in the response, only data. I'd argue that the in-practice and academic standards dictate the opposite, with standards like hypermedia, json schema, HAL, JSON:API, OpenAPI, etc.

If it's just a question about the degree of metadata that should be present then that's one thing, but it sounds like you're against it in general. Once you have any metadata you must have an envelope of some sort, by definition (whether it's a good or bad one), as far as I can see.

Re: How to Design Better APIs

#54

Post by er4hn »

bruhboribhe wrote: post #43
kumarvvr wrote: post #41

Earlier quoted context omitted.

Whoa, completely missed that boat. Is it in active use? Wikipedia page says last spec update was in 2010. No other details online. I could not find any specific implementations.

Active use is really irrelevant if you only plan on using it inside a company, because you can implement a client and server within 30 mins to an hour, no external tools needed. The spec is clear and readable. It's excellent. We use it with a TypeScript codebase and just share the interfaces for the services in a monorepo. The spec is so simple it doesn't really need an update. If you want a more advanced implementat…

Arista Networking uses it in their eAPI protocol. It let's you have machine parsable outputs and avoid ye olde days of screen scraping network device outputs to view interface status and other details.

I believe most users make use of it via an open source json-rpc python lib. You can find a few examples online if you'd like to know more.

Re: How to Design Better APIs

#55

Post by pan69 »

nerdponx wrote: post #35
BulgarianIdiot wrote: post #31

Earlier quoted context omitted.

Well they said use GraphQL, which is a solid way to avoid REST's clumsiness once and for all.

Sort of, but is it any better if the GraphQL layer still has to make 15 requests in order to serve a single useful response?

But those 15 requests are then all occurring over a local network (in the data center), not over the Internet.

The true power with GraphQL is that it might not even make all 15 calls because it will entirely depend on what you are querying for. E.g. if you query for a User but not the Orders for that User, then the request to retrieve the orders is simply skipped by GraphQL.

Re: How to Design Better APIs

#56

Post by tobyjsullivan »

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…

As someone who has spent a decade working with APIs, I 100% agree. The use cases that are a good fit for “RESTful” APIs pale in comparison to those that would benefit from RPC.

What is the point of having your client translate an action to some operation on a document (read or write), only to then have your server try to infer what action was intended by said document operation.

It pains me that this article doesn’t mention any of the trade offs of each suggestion (POST vs PUT vs PATCH and expandable objects, especially) or of using REST APIs generally.

Re: How to Design Better APIs

#57

Post by Supermancho »

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.

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

Re: How to Design Better APIs

#58

Post by askme2 »

spikej wrote: post #44
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 don't think I've ever come across any third party actually implementing HATEOAS ( https://en.wikipedia.org/wiki/HATEOAS )

At OSIsoft, they implement HATEOAS religiously. https://docs.osisoft.com/bundle/pi-web-api-reference/page/he...

Re: How to Design Better APIs

#59

Post by pan69 »

metadat wrote: post #8
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…

Dear PAM69, this is great advice if you want to end up with a slow-to-load, low-performing web application that your customers complain about and hate using. But at least it'll adhere to a specific notion of architectural "purity", right? /s Anytime clients need to make 15 async calls before the UI can be displayed, you're headed up the creek. Generally speaking, this is an anti-pattern. There are exceptions, but the…

Like I suggested, use GraphQL to solve this problem. I know front-end teams that run their own GraphQL server to abstract away clumsy APIs and to optimize client/server requests.
Post reply on HN