4 ms·

A disconnect I often wonder about: People talking about API design: zillions of good discussions online, papers written, standards created, thousands of hours

A disconnect I often wonder about: People talking about API design: zillions of good discussions online, papers written, standards created, thousands of hours of talks at dev conferences, heated debates that nearly venture into philosophy. People implementing APIs: return a 200 response for everything, even an error ¯\_(ツ)_/¯ I know that the people giving talks at strangeloop aren’t always the same people that implement OAuth, but still!! What’s it all for? One guy’s PhD dissertation made us switch from XML to JSON, but beyond that you can rarely count on standards. Least of all REST, even when an API is supposedly REST. Setting up about a dozen OAuth connections to social media ad platforms this year has made me realize that if an API is not a direct revenue stream, it is likely to be pretty bad. And have out-of-date or incomplete documentation.

lmm 2y ago
> One guy’s PhD dissertation made us switch from XML to JSON The PhD dissertation was a rallying cry, something you could point the PhB to as a "best practice". Wanting to switch from XML to JSON had nothing to do with that dissertation, and most of the stuff in there does more harm than good.
arkh 2y ago
The disconnect is simple: you have two populations. One is about consulting, coaching, writing books and speaking at conference to make money. The other is about cranking out code to get things done before some deadline.
inejge 2y ago
People talking about API design: zillions of good discussions online, papers written, standards created, thousands of hours of talks at dev conferences, heated debates that nearly venture into philosophy. People implementing APIs: return a 200 response for everything, even an error ¯\_(ツ)_/¯ Those two are not contradictory; the latter is firmly on the side of the debate which treats HTTP strictly as transport, and considers mapping RPC errors to HTTP errors as a layering violation, inviting ambiguity and semantic mismatches. FWIW, I also subscribe to that view for RPC-shaped requests. If you receive a 200, you know that the request went through to the API server, and didn't become sidetracked on the HTTP level.
- Croftengea 2y ago
  Also, the OAuth RFC does not use "MUST" for 400 response and allows some freedom in this regard: > The authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
- chamomeal 2y ago
  That’s fair, I picked a bad example from the linked article. GitHub is actually pretty good. But if you’ve done any digging around LinkedIn/twitter/Reddit’s API, you’ll know that there are many many quirks that will pop up and cost you days of frustration. Quirks that are not inspired by any particular design philosophy, unless that philosophy is “let’s fuck with our users” lmao
arend321 2y ago
Some of it is confusion about what say a 404 entails, is it the endpoint that does not exist, or that say /api/users returns an empty array for the given search parameters. Some libraries even throw an error if they receive a 404. Probably ambiguity in the HTTP spec.
- chamomeal 2y ago
  You’re totally right, but that was just an example I picked from the linked post. GitHub in my experience is pretty good. But I’ve done a lot of exploring of social media marketing API, and you usually can’t rely on any amount of consistency or convention. At work we have a running doc called “API weirdness” for each platform, where we document the many many undocumented behaviors that will throw you off for a day or two. Reddit is particularly bad. Most of the useful “documentation” is found deep in threads in Reddit itself. Critical bits of information, including the very existence of some endpoints, are only explained in replies written by users!
marcosdumay 2y ago
> People implementing APIs: return a 200 response for everything, even an error ¯\_(ツ)_/¯ Or people implement it correctly, and somebody puts a machine on the middle that converts everything into a 200 response. The web is not a well-behaved platform.

lmm 2y ago

> One guy’s PhD dissertation made us switch from XML to JSON The PhD dissertation was a rallying cry, something you could point the PhB to as a "best practice". Wanting to switch from XML to JSON had nothing to do with that dissertation, and most of the stuff in there does more harm than good.

arkh 2y ago

The disconnect is simple: you have two populations. One is about consulting, coaching, writing books and speaking at conference to make money. The other is about cranking out code to get things done before some deadline.

inejge 2y ago

People talking about API design: zillions of good discussions online, papers written, standards created, thousands of hours of talks at dev conferences, heated debates that nearly venture into philosophy. People implementing APIs: return a 200 response for everything, even an error ¯\_(ツ)_/¯ Those two are not contradictory; the latter is firmly on the side of the debate which treats HTTP strictly as transport, and considers mapping RPC errors to HTTP errors as a layering violation, inviting ambiguity and semantic mismatches. FWIW, I also subscribe to that view for RPC-shaped requests. If you receive a 200, you know that the request went through to the API server, and didn't become sidetracked on the HTTP level.

Croftengea 2y ago
Also, the OAuth RFC does not use "MUST" for 400 response and allows some freedom in this regard: > The authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) https://datatracker.ietf.org/doc/html/rfc6749#section-5.2 https://datatracker.ietf.org/doc/html/rfc6749#section-5.2
chamomeal 2y ago
That’s fair, I picked a bad example from the linked article. GitHub is actually pretty good. But if you’ve done any digging around LinkedIn/twitter/Reddit’s API, you’ll know that there are many many quirks that will pop up and cost you days of frustration. Quirks that are not inspired by any particular design philosophy, unless that philosophy is “let’s fuck with our users” lmao

arend321 2y ago

Some of it is confusion about what say a 404 entails, is it the endpoint that does not exist, or that say /api/users returns an empty array for the given search parameters. Some libraries even throw an error if they receive a 404. Probably ambiguity in the HTTP spec.

chamomeal 2y ago
You’re totally right, but that was just an example I picked from the linked post. GitHub in my experience is pretty good. But I’ve done a lot of exploring of social media marketing API, and you usually can’t rely on any amount of consistency or convention. At work we have a running doc called “API weirdness” for each platform, where we document the many many undocumented behaviors that will throw you off for a day or two. Reddit is particularly bad. Most of the useful “documentation” is found deep in threads in Reddit itself. Critical bits of information, including the very existence of some endpoints, are only explained in replies written by users!

marcosdumay 2y ago

> People implementing APIs: return a 200 response for everything, even an error ¯\_(ツ)_/¯ Or people implement it correctly, and somebody puts a machine on the middle that converts everything into a 200 response. The web is not a well-behaved platform.