21–30 of 44 posts
Programmers are so bad with this, this needs to be a more respected aspect of writing software in general. "Well, I comment everything" isn't enough. If you spent hundreds or thousands of hours on your API, but skimp on the part where you actually look at it from the users' point of view, that's such a colossal waste. You have to multiply the number of future users with the hours wasted on tedious setup hoops and lea…
Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ It was really interesting work and the team was quite committed once we found the right team. People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot. Documentation is the obvious one but lots of other things like structuring the actual information,…
They are amazing (of course I am talking about the right kinds).
http://bryanhelmig.com/your-api-consumers-arent-who-you-thin...
Many APIs are targeted to internal teams creating SPAs nowadays. Maybe the same developer writes both the backend API and the fronted app. Those APIs tend to be a wild west of all the mistakes the post is about. Documentation is often sub optimal, not to talk about vulnerabilities introduced by quick and dirty hacks because the team decides that the backend can trust the frontend (missing validations and missing authorization checks are common in the experience of a collegue working on penetration tests.)
Unfortunately such badly designed APIs are going to hinder the development of new functionality for the time being. We're moving from spaghetti code to spaghetti APIs.
Programmers are so bad with this, this needs to be a more respected aspect of writing software in general. "Well, I comment everything" isn't enough. If you spent hundreds or thousands of hours on your API, but skimp on the part where you actually look at it from the users' point of view, that's such a colossal waste. You have to multiply the number of future users with the hours wasted on tedious setup hoops and lea…
It almost never is.
Everything about the experience sucks. The documentation is usually a mess and the code flow is usually strange as hell. But I can live with that.
It's the completely opaque error states that kill me. The article dedicated an entire section to it and I hope people take it to heart. When I pass bad data or something you're not expecting give me some clue as to what it might be!
I just spent 60+ hours working on an integration. 95% of that was spent changing parameters and encodings hoping that something would magically fix the 400 I kept receiving back from the server.
It turns out a shared secret had a typo (on my end).
The thing is this bad design is costing that company real $$. Not only was it a frustrating experience for me, I took a couple of hours of their engineers time trying to hunt it down. The lack of error handling made it difficult for them to track the issue down on their side as well.
I'll never forget the first time I touched Twilio's API. Everything was so clear. I had screwed something up, and got a clear message about what was wrong. It was magic.. and the whole thing was up and running in less than an hour.
Give me more of that please!
The only breath of fresh air I've had lately is interacting with the NetBox API which uses Swagger to sort of self-document and allow for testing.
Before I left Square earlier this year, I lead our design efforts on the developer API. https://docs.connect.squareup.com/ It was really interesting work and the team was quite committed once we found the right team. People always asked what does a designer do on an API. It turns out that if the team cares, quite a lot. Documentation is the obvious one but lots of other things like structuring the actual information,…
Do you think that the Square API hit the level of design just because of the people involved? Or are there organizational factors that played into it? I.e. was good API design seen at the top as a good reason to take longer with a release? I really want to find suggestions to take into my company.
Everyone who has ever worked with a "proper" API (e.g. Mailchimp) with awesome and intuitive status messages will hopefully never again fail on this. Very bad that this is still not state of the art.
I use it frequently as an example of how not to build an API. I find it hard to integrate efficiently with it - it got worse from version 2 to 3, although some of the blunders have later been fixed.
You're probably right that the error messages are relatively thorough. Many of the constraints aren't documented in the reference documentation, though, so it requires trial-and-error.
However, where is the current trend of functional programming in this piece? (I am not disparaging FP, on the contrary, I think it's a good development.)
Shouldn't API calls be, for example, easy to test? In functional programming, we often avoid doing actions directly, and instead give descriptions of actions (in form of functions) that are to be made. Does your API support that?
What about minimization of the state that the API requires to keep, and its transparency?
I am sorry if I come off a little incoherent. Best would be if I could give some tool a program that calls an API, say a sequence of API calls. And I would be told, this sequence is valid for the API. So I could prove for my program that it is accessing the API correctly.