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