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

201–210 of 238 posts

Re: How to Design Better APIs

#201

Post by id02009 »

aeontech wrote: post #75
pan69 wrote: post #46

Earlier quoted context omitted.

It might be to formal for your use-case, but there is a standard defined for error responses in RFC 7807: https://datatracker.ietf.org/doc/html/rfc7807

Wow, I had never seen an API with errors at this level of detail… I feel lucky when they at least use sane status codes instead of always giving back 200 and a maybe-json-maybe-plaintext-maybe-empty body… I’d love to hear from anyone who has encountered APIs in the wild that actually implement this standard!

I think stripe is close to having decent API in this regard

Re: How to Design Better APIs

#202

Post by inopinatus »

latch wrote: post #121
inopinatus wrote: post #22

Earlier quoted context omitted.

* Human readable * Supports birthdays for people older than 52 * Reliable after 2038 * Supports leap seconds * HTML date/time spec is a subset * String collation order matches temporal order * Excel

> * Human readable Computers are the main consumers of APIs, and ISO 8601 is far from machine-readable. For example, in Elixir, DateTime.from_iso8601/1 won't recognize "2022-03-12T07:36:08" even though it's valid. I had to rewrite a chunk of Python's radidjson wrapper to 1-9 digit fractional seconds (1). I'm willing to bet 99% of ISO8601 will fail to handle all aspects of the spec. So when you say "ISO8601" what you'…

> what you're really saying

No.

The specific profile of ISO8601 that should be used to express timestamps in an API is that defined in RFC3339.

Choosing to use a half-baked parser is a separate matter.

Re: How to Design Better APIs

#203

Post by arendtio »

grishka wrote: post #180
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…

Why use string-based timestamps at all? Use unixtime. It's much easier to parse and it literally can't be malformed.

Sometimes timezones or the like change. So for future dates, those textual represations are probably better.

Example: in November you create an appointment in 6 months at 15h, but then your government decides, to not use summer time next year.

If you use timestamps your appointment will be wrong by one hour (humans tend to keep the 15h).

In general, I am a huge fan of timestamps, but I think it is good to know where they have their limits.

Re: How to Design Better APIs

#204

Post by lkrubner »

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 feel like the whole of the 1990s was devoted to this. How to serialize an object and then what network protocol should be used? But increasingly over time, between 2000 to 2005, developers found it was easier to simply tunnel over port 80/443. In 2006 Pete Lacey wrote a satire about SOAP, which is funny but also accurate, and look at how late people are to discover that you can tunnel over HTTP:

http://harmful.cat-v.org/software/xml/soap/simple

I was puzzled, at the time, why the industry was cluttering HTTP in this way. Why not establish a clean protocol for this?

But people kept getting distracted by something that seemed like maybe it would solve the problem.

Dave Winer used to be a very big deal, having created crucial technologies for Apple back in the 1980s and 1990s, and he was initially horrified by JSON. This post is somewhat infamous:

http://scripting.com/2006/12/20.html#godBlessTheReinventers

"... and damn, IT'S NOT EVEN XML!"

He was very angry that anyone would try to introduce a new serialization language, other than XML.

My point is, the need for a clear a clean RPG protocol, but the industry has failed, again and again, to figure out how to do this. Over and over again, when the industry gets serious about it, they come up with something too complex and too burdensome.

Partly, the goal was often too ambitious. In particular, the idea of having a universal process for serializing an object, and then deserializing it in any language, so you can serialize an object in C# and then deserialize it in Java and the whole process is invisible to you because it happens automatically -- this turned out to be beyond the ability of the tech industry, partly because the major tech players didn't want to cooperate, but also because it is a very difficult problem.

Re: How to Design Better APIs

#205

Post by chaz6 »

hinkley wrote: post #116
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…

Localization has entered the chat. You need codes because the field isn't going to be 'email' for much longer than it takes for your management to realize that people outside of the US also have wallets.

My view is that apis should simply return a number when an error occurs. The vendor should supply a list of error codes to its consumers, translated into as many languages as necessary. The developers who are consuming the api can then determine how best to present the error to its end users. A set of error numbers is tied to the version of the api that is being consumed so there should be no surprises.

Re: How to Design Better APIs

#206

Post by grishka »

arendtio wrote: post #203
grishka wrote: post #180

Earlier quoted context omitted.

Why use string-based timestamps at all? Use unixtime. It's much easier to parse and it literally can't be malformed.

Sometimes timezones or the like change. So for future dates, those textual represations are probably better. Example: in November you create an appointment in 6 months at 15h, but then your government decides, to not use summer time next year. If you use timestamps your appointment will be wrong by one hour (humans tend to keep the 15h). In general, I am a huge fan of timestamps, but I think it is good to know where…

> Sometimes timezones or the like change.

Why would you ever want anything to do with timezones in an API? Even for appointments, it's still a timestamp. Timezone should be applied the very last moment, as part of date formatting for output on the client.

If you allow your users to create appointments this much in advance and then they miss them, it's a UX problem, not an API design problem.

Re: How to Design Better APIs

#207

Post by ComputerGuru »

ceeker wrote: post #82
ComputerGuru wrote: post #71

Earlier quoted context omitted.

I upvoted because I'm curious to hear what others are doing. We typically make sure to only make such breaking changes where either the now-required value or a sane filler value could be used. If it's the same API for the same purpose, it's usually not a stretch to assume the values for a new field are derived from some combination of an old field or else are primitive components of an old field such that they can be…

Thanks. This is a fair point. I made up the example only to illustrate the idea. Since Stripe is considered some sort of benchmark here I was curious to see how they tackle all the learnings they will have over time...I feel it is very hard to think through all the future cases especially when you are just about starting out with your product. For example, in financial services and insurance, regs change and what dat…

No worries, I understood it was a throwaway example that shouldn't be looked at too closely. You just have to remember that your DB isn't a model of what you want to require from your customers but rather a model of what you actually necessarily have and don't have. A field like the ones you're talking about shouldn't be marked non-nullable in the database if there's a chance you actually don't have that data (and when you are suddenly required to collect something you didn't have before, you're not going to have it).

Coming at this from a strongly-typed background, you acknowledge the fact that despite new regulations requiring a scan of the user's birth certificate in order to get an API token, that field can't be marked as non-null if you don't in fact have all those birth certificates. You are then forced to handle both the null and not-null cases when retrieving the value from the database.

So your API v2 can absolutely (in its MVC or whatever model) have that field marked as non-null but since your API v1 will still be proxying code to the same database, your db model would have that field marked as nullable (until the day when you have collected that field for all your customers).

If a downstream operation is contingent on the field being non-null, you are forced to grapple with the reality that you don't have said field for all your users (because of APIv1 users) and so you need to throw some sort of 400 Bad Request or similar error because (due to regulations) this operation is no longer allowed past some sunset date for users that haven't complied with regulation XYZ. In this case, it's a benefit that your db model has the field marked as null because it forces you to handle the cases where you don't have that field.

I guess what I'm saying is the db model isn't what you wish your data were like but rather what your data actually is, whether you like it or not.

Re: How to Design Better APIs

#208

Post by bluefirebrand »

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…

My current company has settled on "We use GET to retrieve data from the server and POST to send data to the server, nothing else" because it was causing quite a lot of bikeshedding style discussions where people were fussing over "Should this be a post, put or patch"?

It all came to a head when someone wrote an endpoint using a PATCH verb that some people were adamant should have been a PUT.

It was among the most silly nonsense I have ever been a part of and these discussions have thankfully gone to zero since we decided on only GET and POST

Re: How to Design Better APIs

#209

Post by bluefirebrand »

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 )

I had a new hire on my team criticize the API we built for our product because we don't use put or patch, and we don't allow a GET and POST to share the same path. He said "it's not very RESTful"

I pointed him at HATEOAS and suggested if he wasn't familiar with it, he probably hasn't ever seen a truly RESTful API.

I don't think I convinced him that our approach is good (I'm not sure I am convinced either, but it works well enough for our purposes)

I do think I convinced him that "it doesn't correctly conform to a standard" isn't necessarily a useful critique , though. So that's a win.

Re: How to Design Better APIs

#210

Post by bluefirebrand »

incrudible wrote: post #165
darkstar999 wrote: post #115

Earlier quoted context omitted.

What?

This answer is correct, but lacks context. REST wasn't conceived with APIs in mind. In fact, it's an awful fit for APIs, as many of the other comments point out. Rather, REST today is a buzzword that took on a life of its own, bearing only superficial resemblance to the original ideas. HATEOAS is a generalization of how something like a website would let a client navigate resources (through hyperlinks). It requires a…

Absolutely agreed on all points.

The best APIs I've ever used or built have been, at best, REST-ish.

And generally the parts where they deviate from REST make them more usable, not less.

Post reply on HN