An API is a user interface(arp242.net)
arp242.net
An API is a user interface
https://www.arp242.net/api-ux.html
53 comments
> Programmers are the exclusive consumers of the Application Programming Interface
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.
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 is true that "programmers are users, too" but this is like saying that tomato farmers also eat tomatoes; the farmer and the chef have different concerns.
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 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.
A farmer is not the one designing the farm equipment (though I respect how much they know and may be able to do maintenance on it). That's where this analogy breaks down. The original suggestion that APIs are less UX than UIs is based on the idea that developers make APIs and thus will easily understand other APIs, so that less investment in the experience is needed. Which is... nonsense? First of all, not all developers are API developers. Those in other disciplines will welcome the assistance provided by good design and documentation. Secondly, as much as I don't appreciate diving into someone else's spaghetti code, do I also not appreciate integrating with someone else's clunky API, even though I build APIs for a living.
>>>> this is like saying that tomato farmers also eat tomatoes
>>> 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
>>> 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
> Programmers are the exclusive consumers of the Application Programming Interface, while users don't have to know about it.
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".
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".
An AP Interface, is the way for the programmer to act as the User of this Interface. It IS a user interface.
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.
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.
There's a massive difference between a back button and gl.texParameterf().
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.
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.
A back button is a GRAPHICAL User Interface.
Code/APIs are a different type of User Interface. Maybe we can call it PUI for Programmer User Interface.
Code/APIs are a different type of User Interface. Maybe we can call it PUI for Programmer User Interface.
No one said a back button isn't a user interface, the person you replied to just said that they were very different.
Not to pick on this person, really, but I saw the picture and noted he said "20 years experience" and I thought, hrm, he looks kind of young. CV then says he has been programming since he was 13.
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?
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?
"Experience" is always tricky to define; is a part-time job "experience"? Is spending 20 hours/week on free open source stuff "experience"? I definitely spent an insane amount of time programming all sorts of stuff that don't count a experience in the classic CV sense, but that I did learn a lot of things from. I've also known people that have been in the same job for years and don't seem to learn a thing. So idk.
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.
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.
I think "experience" is too ambiguous to be useful, honestly.
I don’t really agree with the premise. The core logic of a program can (optionally) interact with humans and/or other systems. With neither, one is left with a “run to completion” program that typically transforms its OS supplied inputs into outputs.
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?
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?
Even a “run to completion” program has a user interface: the command line options, configuration files, etc. And in the Unix programming environment, a command-line program is also an API.
The way I read it was:
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.
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.
> When you use an interface, you are a user.
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”?
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”?
Yes, a programming language being a user interface is a common analogy.
>documented with awkward English
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.
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.
It's not that hard, and native English speakers are just as bad at it as non-native speakers. The problem isn't with less than perfect English language skills, it's about just taking some care to ensure it reads nice by using appropriate interpunction, paragraphs, is reasonably comprehensive, doesn't just lazily tack on "oh, this too" lines at the end instead of rewriting the paragraph, and things like that.
Of course if your audience prefers a different language, let's substitute English for the other language. If your point is that a good programmer (of APIs) may not write perfect documentation (or even bad documentation), maybe that's exactly where you could treat your API as a first class citizen and bring in a technical writer. I'm not saying that's worthwhile for every API being developed. But if you want to build a first class product, and bring in designers and what not for the UI, why would you neglect the API.
I don't disagree in general. Although, as a founder, I can tell that in practice providing first-class documentation is less trivial than it sounds. Not everybody has the Apple's or Google's money. Technical writers are not cheap. Also technical writers tend to have problems understanding how a system works, because they lack the knowledge of the system's internal logic. Therefore, developers should be involved in writing documentation too which makes it even more expensive and tedious process. Then software changes and documentation has to be partially rewritten again.
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.
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.
I was trying to acknowledge the tradeof ("I'm not saying that's worthwhile for every API being developed"). I was arguing that API documentation is not bad because there is a developer with "awkward" writing abilities, rather it is bad because of choice. Which might be the best choice for your situation, but still.
Some developers just write bad documentation. Some spend so much time in the weeds that when it comes time to write the documentation, they write a garbled string of words that tries to address all of the edge cases with not enough emphasis on the core usage. Others don't know how to express the concept of a feature in a simple and straightforward manner.
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.
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.
This is why plain, semantic, html forms are great: you get API documentation and GUI in one machine readable file.
An API is a political boundary.
no.api is the main interface of programmer
API as a term is context-dependent. It is one of those terms where it is easy to cause disagreement—as is evident in this thread—because you failed to define what you really mean by your use of the term.
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:
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.
The I in API stands for Interface.
Is the P for programmING or programmER, though?
Programming, and the "A" is for application, and the application is a user. Albeit, one that is not human, but programmed. So the programmer is programming the application user to behave in a way that can interface with the application exposing the API.
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...").
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...").
Is for ing, should be for er
p for programmer,
Hahaha exactly, most time if you people just look at the alphbetical soup is, then they will get the answer.
literally. programmers are users too
> I tend to start by writing a few basic usage examples and documenting it
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.
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.
Documentation driven design.
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.
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.
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.
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.
When 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.
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.
This 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.
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.
This is a corollary to that code should be written foremost to be understood by humans, and only secondary by computers. It’s not only true for interfaces.
I was first exposed to this idea by this article: https://www.drdobbs.com/windows/measuring-api-usability/1844...
The author of that article - Steven Clarke - is here on HN and often posts on this topic.
The author of that article - Steven Clarke - is here on HN and often posts on this topic.
> I’m not going to list specific examples or tips here, as tastes and conventions differ anyway. There usually isn’t “one right way”.
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/
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 argue that more work (at least 50% more) should be put in documenting APIs. Technical writing is a lost art.
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...
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...
I've grown to like unstructured documentation, rather than the more structured headerdoc/doxygen and the like. If you write it well as prose I find it's often clearer. With doxygen it sometimes feel like filling in a bureaucratic form rather than actually writing documentation (and it often reads like it, too).
Completely agree. The headerdoc stuff is just for a reference.
I omitted specific examples as it's just really tricky to make them general. It really depends on the environment, intended audience (kernel programmers are not Rails programmers), and most of all: what you're doing.
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.
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.
Like Apple. They used to set the bar for documentation.
Nowadays...not so much (I'm looking at you, SwiftUI).
Nowadays...not so much (I'm looking at you, SwiftUI).
> 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"
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.
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.
> 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.
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.
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.
There are established "ways of doing things" in API design, but they are manifold and conflicting because there are major technical constraints and traditions and more importantly vastly different needs. While, for example, graphical techniques to make interactive elements in a GUI stand out from read-only content are partly universal and partly consolidated by tradition, even a noncontroversial principle like providing "apt documentation" is an abstract concept that can have a very different meaning for different people and in different situations.
The point is that conflating these cheapens both disciplines. A good API may last decades, a good UI can float across multiple APIs.