An API is a user interface
arp242.net
arp242.net
The point is that conflating these cheapens both disciplines. A good API may last decades, a good UI can float across multiple APIs.
That's the point. Programmers are the users of APIs. So build them for users, to support them in their work; don't build them programmers who need to hack around the API to get things done.
> while users don't have to know about it.
There is no difference between programmers and users. Everyone is a user, it's just a matter of perspective. If you creat an API you are the programmer, if you use an API you are the user. In both cases you have different knowledge, understanding and goals.
It's not a good analogy because programming APIs are only used by the programmer. If this is an internal API then it's akin to the farming equipment that a tomato farmer might use to supply the chef with high quality tomatoes.
A farmer using high quality, efficient equipment will have an easier and more productive time farming tomatoes and therefore will have an easier time fulfilling the needs of chefs who want the tomatoes.
It's still very much a user interface. The users are your developers. I think people are confusing graphical user interfaces with user interfaces. A keyboard/mouse is a user interface into a PC.
If it's a public API then the API is your product. And it's very much a UI because that is the user interface, the users use your product in that way. That's why companies like Stripe are so loved by developers, they have a good API.
>>> it's akin to the farming equipment that a tomato farmer might use
>> A farmer is not the one designing the farm equipment
Great example of the problem of using analogies.
> someone else's spaghetti code
I'll not open this, erm, can of worms
What should be taken seriously is proper domain and service modeling. The rest follows.
A good UI follows a good model. Visuals and trends are just a tiny bit.
I honestly have no idea what "proper domain and service modeling" means but a good UI is NOT a natural consequence of good engineering. That's why human interface design is a real discipline.
Code/APIs are a different type of User Interface. Maybe we can call it PUI for Programmer User Interface.
The term "user interface" is perhaps a bit unfortunate, and "human interface" would be better. In my usage of "user" here it's a synonym for "human".
This is exactly what I do. Before I even think about the internals of a function, module or endpoint, I imagine that it exists in the ideal form that I or any other programmer would want, and then write a few usage examples. Then I pick the best one and implement it.
I nearly always start at the exposed API and try to make it make sense, then design code and models that enable that interface. The API is your product.
The philosopher in me doesn't mean to be snarky, but what the author concedes here is that APIs actually aren't like user interfaces. Because when we're talking about UIs, there are most definitely "ways of doing things" and "ways of not doing things" -- after 50-odd years of user interfaces, we ended up with scrollbars and buttons and tabs for a reason.
The point is interesting, but lacks force without actual examples. APIs can vary immensely in application: some might take huge arrays of data, others might take neatly formatted arguments, others might just consume bit streams. There's certainly a point to be made about the ergonomics of an API, but -- even though I may have an intuitive feel for it -- I'd need to think more about how to exactly explain what I mean. I have a feeling the author is in the same boat.
Further, there's a fundamental element of documentation when dealing with APIs. Even the most unwieldy[1] API can be grokked if documentation is apt. I'd argue that more work (at least 50% more) should be put in documenting APIs. Technical writing is a lost art.
[1] https://docs.microsoft.com/en-us/windows/win32/api/winuser/
I’d suggest 100% more.
I use headerdoc (Doxygen-style) code comments all the time[0]. That helps, but is not perfect. It’s still better than nothing.
Structuring an API, so that the internals are sequestered, is (IMNSHO) important. I like to have the lions’ share declared private or protected.
Test harnesses (as opposed to unit tests) are pretty effective examples[1].
[0] https://littlegreenviper.com/miscellany/leaving-a-legacy/
[1] https://littlegreenviper.com/various/testing-harness-vs-unit...
For example, sometimes a single function with 5 parameters would be bad UX, whereas in other cases it might be a good option, if all 5 really are mandatory for example, or if you use Python and have named parameters. In other cases, it makes more sense to have 5 functions which accepts a single parameter (no one likes "foo(true, true, false, true, false)").
Not all GUIs are the same either; specialist tools can get away with certain "difficult" UI conventions, since people will be trained for those tools, whereas GUIs can't. A lot of design choices are trade-offs without a single objectively "best" solution.
I actually trimmed down the article quite a lot from the original draft I wrote over a year ago, since I didn't want to get bogged down in "details" about these kind of things, as I could think of a whole bunch of exceptions for every general piece of advice. So instead I opted to try and get the bigger point across that an API (any API) is something humans need to interact with, and is a "user interface".
As for documentation: yeah, I agree. I actually like writing documentation and I'm often dismayed by the poor quality documentation out there, even from people or organisations I know can do better.
Nowadays...not so much (I'm looking at you, SwiftUI).
There are definitly things you should not do, but there hardly is a list ot things you always should do. There is just no gold list of thing in UI, just customs and established conventions to enforce the "intuitive level" of interactions.
But even between different platforms you have strictly different conventions, sometimes even competing with each other. Yet most of them are good on their own and it's wrong to use one of them.
> after 50-odd years of user interfaces, we ended up with scrollbars and buttons and tabs for a reason.
Yet wie have working interfaces without scrollsbars, buttons and tabs, even where they could be used, and some cases where using them even makes the interaction worse.
UI is more a kind or prioritylist of things you can add, not a checklist of things you should add.
I'd say that the 'proper' API design depends very much on the language you target, at least when you come to details. However there are a few overarching principles of UI design which also hold for API design such as consistency (in my view the most important part of UI design) or discoverability.
In my view resorting to documentation is a second line of defense. The first line being able to understand intuitively. This is one reason I prefer libraries over frameworks. The latter almost always require documentation for working with them (you need to implement these 5 interfaces and put them into this factory,...). The former done right are almost always intuitively understandable.
Hence, and API is a UI. When I write user stories, all external applications are users (e.g., Payment Processor User), and the internal application is the system user ("As the System, I would like to...").
I see this A LOT as of late. People are counting high school side projects as real world experience... but that is not exactly the same as on the job experience. I am NOT knocking the awesome work you did in high school, hell, as an EE person, I could say I designed circuits when I was 12, but I would never add 10 years to my CV or my blog by counting it.
Honest question: is this the new norm?
At any rate, I updated it to 15 now; which is job experience + 2 (soon + 1, when it's 2021), which seems more than fair. I should probably rewrite this tagline entirely.
A “user interface” is associated with human interaction, whereas an API is associated with interaction with other systems. That human interaction is in terms of the user of the program, not the producer.
That programmers are human, might mean that they need to program against an API, but surely that doesn’t mean that the term “user interface” should be extended to it?
When you are programming against an API, you are using the interface. When you use an interface, you are a user. You are even the expected User from the API designers perspective. You are that API designers customer. In your job as the User of that API, you also have different customers you serve. But that doesn't mean you are no longer a User of the API. Because you are the user in this case, using an API, then that must mean your going to have a User Experience with that User Interface that just happens to be in a API.
It’s an interesting perspective. I guess by extension, that the use of a programming language, makes the programmer a user of the resultant program, and the language a “user interface”?
Sorry, not everybody on Earth has perfect English. The author has a point about APIs being UIs but remarks like that make me think his expectations are a bit too idealistic.
All in all, not every car is a Mercedes and not so many people can afford a Mercedes. Companies frequently don't provide best-in-class API documentation not because they are lazy (although it can happen too), but because it's always a trade-off: should the money be spent on improving documentation, or invested into new features. It's a matter of priorities and balancing between them. For some products API is the top priority, for some isn't.
As a member of a Developer Experience team, I can confidently say that good documentation does not require a "certified" technical writer. Good API documentation just requires that another person, who has not worked on the feature, review the documentation in code review.
As a founder, it should be important to you that your business is providing the best possible value to your customers. If your business is providing an API, then you should cater to the developers who will be consuming that API as much as you are catering to the executives who will be signing the paperwork.
English also happens not to be my first language :-)
The author of that article - Steven Clarke - is here on HN and often posts on this topic.
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.
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.
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.
API is a term of art—it means different things to different practitioners. What the term means to you will depend on where you work on the stack.
For a web-based application served over the Internet:
- an end user will need to work visual APIs (web GUIs) rendered using HTML/CSS/JS;
- a frontend engineer will need to work with text-based APIs (web services) exposed by web servers on the Internet;
- a backend engineer will need to work with system APIs exposed by web & DB servers over the internal network;
- a DBMS engineer will need to work with low-level APIs exposed by the OS to internal processes.