How to Design Better APIs • Hacker News Board

Re: How to Design Better APIs

#151

Post by brigandish » Sat, Mar 12, 2022, 11:39 AM UTC

darkstar999 wrote: post #115

JimDabell wrote: post #86

Earlier quoted context omitted.

Chrome, Safari, Firefox, Edge, and Opera are all third-party clients for the HATEOAS-based API known as the World-Wide Web.

What?

The classic book on the subject is RESTful Web APIs[1], and it spends a while explaining HATEOAS by using the example of the web as we've come to expect it as the exemplar REST API using HATEOAS. I also have this essay[2] on HATEOAS in my open tabs, and it uses the example of a web browser fetching a web page.

[1] https://www.oreilly.com/library/view/restful-web-apis/978144...

[2] https://htmx.org/essays/hateoas/

Re: How to Design Better APIs

#152

Post by athrowaway3z » Sat, Mar 12, 2022, 11:41 AM UTC

11235813213455 wrote: post #147

Something I wonder is how to design search/list endpoints where the query can be long (a list of IDs, ex: /users?ids=123e4567-e89b-12d3-a456-426614174000,123e4567-e89b-12d3-a456-426614174001,123e4567-e89b-12d3-a456-426614174002,...), so long that it can exceed the url max length (2048), after 50 UUIDs, you can quickly exceed that length, so GET is not ideal, so which method, SEARCH with a body? POST with a body?

The type signature:

` list of uuids -> list of results `

is usually bad design to begin with.

Re: How to Design Better APIs

#153

Post by ChrisMarshallNY » Sat, Mar 12, 2022, 11:47 AM UTC

It’s a good posting. I do many of these things, but not all.

I’ve been designing SDKs for a long time; APIs, for a somewhat shorter time.

I don’t like “pure” RESTful APIs, because I feel as if they are “human-hostile.” I tend to follow the patterns set by companies like Google, where the stimulus is a fairly straightforward URI (with parameters, as opposed to a block of XML or JSON —if possible, as I know that we often still need to send big data as transaction data, which can be a pain, depending on the method), and the response is a block of structured data. That also makes it a lot easier for API clients to build requests, and allows the server to “genericize” the processing of requests.

> 10. Use standardized error responses

Is something I do, along with a text header payload, describing internal information about the error. It is my experience that this text payload is never transferred, and I am forced to send a text response via the body, if I want to know internal information. That can be a pain, as it often breaks the transaction, so I have to play with the server and client, frequently, using a cloned server instance.

I should note that my forte is not backend development, so the chances are good that I am not familiar with all the tools at my disposal.

Re: How to Design Better APIs

#154

Post by thatwasunusual » Sat, Mar 12, 2022, 11:56 AM UTC

ChrisMarshallNY wrote: post #153

It’s a good posting. I do many of these things, but not all. I’ve been designing SDKs for a long time; APIs, for a somewhat shorter time. I don’t like “pure” RESTful APIs, because I feel as if they are “human-hostile.” I tend to follow the patterns set by companies like Google, where the stimulus is a fairly straightforward URI (with parameters, as opposed to a block of XML or JSON —if possible, as I know that we oft…

> I tend to follow the patterns [...]

Can you elaborate on this? Give examples?

Re: How to Design Better APIs

#155

Post by kuon » Sat, Mar 12, 2022, 12:01 PM UTC

ISO 8601 is bad, use RFC 3339.

A lot of implementation are actually based on an ISO draft which changed in final release. But most dev do not have access to the spec. For example, timezone can only be specified as offset in the standard, while implementations accept name.

Globally avoid ISO for software, it is non free crap.

Also, do not use those standard for dates with timezone in the future. Use wall time/date and location. As timezone can change way more often than you think.

Re: How to Design Better APIs

#156

Post by ChrisMarshallNY » Sat, Mar 12, 2022, 12:04 PM UTC

thatwasunusual wrote: post #154

ChrisMarshallNY wrote: post #153

It’s a good posting. I do many of these things, but not all. I’ve been designing SDKs for a long time; APIs, for a somewhat shorter time. I don’t like “pure” RESTful APIs, because I feel as if they are “human-hostile.” I tend to follow the patterns set by companies like Google, where the stimulus is a fairly straightforward URI (with parameters, as opposed to a block of XML or JSON —if possible, as I know that we oft…

> I tend to follow the patterns [...] Can you elaborate on this? Give examples?

I don’t feel like doing that in a comment, but feel free to check out some of my work. The BAOBAB server[0] is one of my more recent examples. I’m using a modified version as the backend for the app I’m developing, now. It works great.

I should note that the BASALT layer uses “plugins,” that can be extended to include “pure” REST APIs. I just haven’t found these practical, for my purposes.

[0] https://riftvalleysoftware.com/work/open-source-projects/#ba...

Re: How to Design Better APIs

#157

Post by sigmaml » Sat, Mar 12, 2022, 12:27 PM UTC

borrow wrote: post #132

sigmaml wrote: post #112

Earlier quoted context omitted.

You appear to be referring to a database cursor. It is quite simple to implement pagination in the application layer using a unique record identifier (primary key or ULID or ...) as an anchor for the navigation. From that unique ID, we can then fetch the previous `n` or the next `n` records, depending on the direction of the navigation. This way, the server remains stateless, since the anchor (possibly sent as an enc…

What if that particular unique ID is deleted right before the client requests the next page?

1. This kind of pagination can be done for any key as long as its data type admits total ordering.

2. The WHERE condition typically uses `>` or `<`, so it doesn't fail even when that record is deleted before the next client request referring to it.

Re: How to Design Better APIs

#158

Post by berkes » Sat, Mar 12, 2022, 12:28 PM UTC

pmontra wrote: post #137

spikej wrote: post #44

Earlier quoted context omitted.

I don't think I've ever come across any third party actually implementing HATEOAS ( https://en.wikipedia.org/wiki/HATEOAS )

I used some API recently that returns URLs in the response body. It's really useful because they maintain those URLs and we don't have to rewrite our URL building code whenever the server side rules change. Actually we don't even have to write that code. It saves time, bugs, money. I don't remember which API was that, I'll update the comment if I do.

Better yet, those URLs communicate what you may do.

Instead of building the logic to determine if, say, a Payment can be cancelled, based on its attributes, you simply check 'is the cancel link there'.

I find this a critical feature. Because between the backend, and various mobile clients, react, some admin, and several versions thereof, clients will implement such businesslogic wrong. Much better to make the backend responsible for communicating abilities. Because that backend has to do this anyway already.

Re: How to Design Better APIs

#159

Post by idoubtit » Sat, Mar 12, 2022, 12:29 PM UTC

kuon wrote: post #155

ISO 8601 is bad, use RFC 3339. A lot of implementation are actually based on an ISO draft which changed in final release. But most dev do not have access to the spec. For example, timezone can only be specified as offset in the standard, while implementations accept name. Globally avoid ISO for software, it is non free crap. Also, do not use those standard for dates with timezone in the future. Use wall time/date and…

My own experience is that (unix) timestamps are much less error-prone than textual representations like ISO 8601 and such. A field like `update_time_seconds` is clear and easy to convert into any representation. This is what the Google API Improvement Proposals recommends in most cases, though civil timestamps are also described. https://google.aip.dev/142

Of course, when preparing queries against the API, you may need a helper to build valid timestamps. But this is mostly relevant to the discovery phase which isn't automated. And textual dates also have drawbacks, for instance the need to encode it when used a an URL parameter.

Re: How to Design Better APIs

#160

Post by RedShift1 » Sat, Mar 12, 2022, 12:36 PM UTC

synthmeat wrote: post #139

JaggedJax wrote: post #14

Earlier quoted context omitted.

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.

We're querying dozens, if not into hundreds, of GraphQL APIs for a couple of years now. Terrible DX, terrible performance, terrible uptimes. Everyone on the team, with no exception, hates them. Even a lot of those who produce them cobble together a bad REST implementation for parts of their own products. Agreed even at rate limits comment - frequently, probably in moments of desperation, they rate limit according to…

> Terrible DX

Can you elaborate what's terrible about the developer experience? If anything it's much better than REST, even if the developer of the API doesn't bother with documentation, the GraphQL schema is fully usable as documentation. Plus the way to input and output data into the API is standardized and the same across all GraphQL API's.

> terrible performance

How? Is the API slow to respond? Or are you making too many calls (which you shouldn't do) increasing the round trip time?

> terrible uptimes

I fail to see how that uptime is related to GraphQL. REST API's can be just as unreliable, if the server is down, the server is down and no technology can fix that.