3 ms·
Treating APIs as the same as GUIs means introducing discoverability, the primary advantage of GUIs over e.g command line. Discoverability in an API would norma
by abraae 6y ago
Treating APIs as the same as GUIs means introducing discoverability, the primary advantage of GUIs over e.g command line.
Discoverability in an API would normally imply HATEOAS / hypermedia, the altar at which REST zealots worship.
But whereas the discoverability provided by GUIs are very real and well accepted, the evidence is nothing like as clear for HATEOAS.
Sure it's nice when you're noodling around in curl to spot a handy url taking you to the next page of results, but I'm really not sold on the benefits beyond that.
In a GUI, we are typically trying to achieve a task and then get out. Did I manage to add that txt record to my dns entries in Route 53? Success, and case closed.
But when I'm playing with an API, I'm typically trying to understand how I will later automate my interactions with it. I'm not trying to achieve a one off end goal - instead I'm trying to understand how to write code that will - later - achieve that end goal over and over again.
These are fundamentally different scenarios, and that explains why documentation is so important for APIs. I doubt that many people have ever jumped into any reasonably complex API using curl or postman or whatever, and then worked out from the responses everything they need to know to write their code. Nope, they used the documentation. They didn't reap the theoretical benefits of HATEOAS.
tldr; APIs are really nothing like UIs.
- arp242 6y agoThis isn't just about REST APIs though, but about APIs in general. e.g. a "dosomething" package or class you add in an application, or as a stand-alone library. REST APIs are a tiny part of all APIs. You're right that GUI's aren't completely analogous to commandline UIs or API UIs; every form of UI has its own strength, weaknesses, and different audiences. Treating APIs as exactly the same as GUIs would indeed be a mistake, but the main point is that they're something a user interfaces with: that is, they're a "user interface", and it's useful to think of it as such right from the start.
- IggleSniggle 6y agoWhen I write the method names for a class, I think carefully about what names to provide that will lead the reader in the right direction for understanding how everything fits together. I provide examples that give a few options for how the reader might achieve various goals. And I keep the number of methods small enough to be digestible as a single unit. That is to say, a class is basically a “view” for interrogating one aspect of how the program works. If I didn’t care about the user interface of it, I wouldn’t bother picking names, writing documentation, or providing examples. HATEOAS is an interesting thing to bring up, because I’ve always felt that it’s biggest benefit was for programmatic interrogation of an API. If it has a good UI, then the endpoints it references will make sense to me by reading the names, sure, but I can also get that from, say, the documentation. And what is the purpose of documentation? Discoverability. A bad user interface for an API looks like this: the names don’t make sense, the collections are inconsistent, there is no documentation, and it’s difficult to find examples where it is used. Each one of these areas are the areas where you are creating a specifically user-oriented interface for your program. Some of them may happen to a degree by accident, like having a working example simply because it is not dead code. But if, say, it is a metaprogramming API, it may be difficult to find where the working example actually exists without some guidance. The way you structure your code will make stumbling onto the example easier or harder for your APIs user.