mirror of
https://github.com/semver/semver.git
synced 2026-03-24 03:51:58 -05:00
Misuse of the term API #457
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: github-starred/semver#457
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @designermonkey on GitHub (Feb 23, 2021).
API stands for Application Programming Interface, and is only one of many types of interface in a software system. All different types of interface can declare a 'public interface'.
Using the term 'public API' in item 1 is a misnomer as there is also possibility, for example of a 'public GUI' and a 'public CLI'. Technically this document does not support CLI or GUI codebases as it is limiting itself to API only.
Please consider updating the document to explain this peoperly, using th term 'public interface' for a more accurate explanation.
@ljharb commented on GitHub (Feb 23, 2021):
This document absolutely supports a CLI or a GUI, as both of those have an interface with the user.
@designermonkey commented on GitHub (Feb 23, 2021):
Yes they do have an interface and that is what I am pointing out, however the document uses the term API explicitely, so in strict terms of a technical specification, the document does not support GUI or CLI being that only API is defined.
As a human being, I cannot interact with an API without the use of something like a CLI or GUI, being that I am not a computer system.
API is an acronym meaning Application Programmable Interface, which is exclusively not the same as a User Interface or Command Line Interface, all of which have a 'public' interface.
This is about using the right nomenclature to describe meaning accurately. Wherever the term API is used in the document, it should be replaced with PI or Public Interface, as that is what it is in fact describing.
@ljharb commented on GitHub (Feb 23, 2021):
The term API is already inclusive of guis and clis. A CLI is an API, as is a GUI. The term API is the proper nomenclature already.
@0ank commented on GitHub (Feb 23, 2021):
Excuse me, I don't know whether it will help with solving this problem or not, but:
@designermonkey commented on GitHub (Feb 23, 2021):
I'm sorry but that is not accurate. (The comment previous to @ankiedos one above)
Each term is quite explicitely defined for it's purpose. Each of these references does in no way mention any of the other terms as they are mutually exclusive of each other.
A CLI is not an API by the clear definitions of each of those terms.
Just because it is generally thrown about as a term does not make it's use correct.
I would like to hear other's opinions on this.
@ljharb commented on GitHub (Feb 23, 2021):
The term API is an umbrella term. I’m sorry you don’t understand it that way, but it has long been the case, and continues to be.
Descriptivism in linguistics means that what’s correct is the way it’s used, and that common usage makes the dictionary wrong, not the other way around.
@designermonkey commented on GitHub (Feb 23, 2021):
Please provide documented reference of proof of that claim.
This may be the case in passing speech and I won't disagree with that as I use it too, but this is a technical specification document; it has to be accurate to the known referenced use of language.
@0ank commented on GitHub (Feb 23, 2021):
When I read more about it, i saw that in the list of types of user interfaces, on positions 3 and 9 there are CLIs and GUIs, but there aren't APIs.
Second thing I saw was that in the list of interfaces in common, API wasn't in the node named "user interface", when GUI was there.
On the other hand, I saw on wikipedia, that "API can use components of GUI".
So I came to the conclusion, that it is unresolvable problem.
@jjlharrison commented on GitHub (Feb 23, 2021):
If I write an application that interfaces with a program via a CLI, or even via automated use of a GUI, then that CLI or GUI are an API to me. Semver only makes sense in this context when those tools serve as an API.
@designermonkey commented on GitHub (Feb 23, 2021):
I'm not wanting this to become an argument, simply to change
public APIorAPIreferences topublic interface. If it is required to define what that means, then more adjustment of the document may be needed.I do understand how language works, and that we all have different opinions on definition, which is why clear definition is important. Names have meaning, especially in enterprise situations where you have to get regulatory validation and agreement (as I do at present). The spec should avoid possible ambiguity by using the most clear and non-specific terms as possible.
If this were a legal contract a lawyer would pick this apart; I've seen it happen as I worked a number of years in legal tech.
@ljharb commented on GitHub (Feb 23, 2021):
https://www.mulesoft.com/resources/api/what-is-an-api
The common definition, which would absolutely hold up in court, is that an API a is anything you interact with, including a CLI and a GUI.
Changing the document to “public interface” would be more confusing, because “interface” is ambiguous while API is very unambiguous and years since understood to have this definition.
@0ank commented on GitHub (Feb 23, 2021):
In this link definition of an API is like on this schema:
App's GUI/CLI <--API--> App
Because:
So API is software-software interface and user interfaces (GUI/CLI) are something like human-(software-software interfaces) interfaces or, more seriously, human-software interfaces.
@ljharb commented on GitHub (Feb 23, 2021):
This was just the first google result i grabbed; there’s tons more that support the interpretation of “api” that every reader of this document, and most importantly, platform and package maintainers, have inferred for a decade.
@0ank commented on GitHub (Feb 23, 2021):
Oh, I found API definition, which is the same as I use: API is a library or framework, e.g. Node.js, WPF, Qt, Bootstrap, etc. (because Application Programming Interface), but I don't want to argue with You.
Goodbye.
@klehelley commented on GitHub (Feb 24, 2021):
The way I see it, the intended scope of SemVer was initially about software-software interactions. Not sure if that is still the case in the mind of the maintainers, however.
As such it is debatable whether SemVer is usable with GUIs and CLIs, in the context of human-software interaction, but these interfaces can totally be used by other applications (in which case I consider API to be a suitable umbrella term -- that could also cover ABIs in projects that care about them). Most obvious is using an application via CLI in scripts. There is also the use of accessibility tools to interact with a GUI. However a project manager can document that these should not be considered part of the public API, and that when used by other software there are no guarantees given when upgrading even between PATCH versions. That would be completely fine by me.
@ghost commented on GitHub (Feb 26, 2021):
Technically any CLI that has documentation with the standard
--helpflag and any GUI that is documented has an API. If there's any confusion, an API isn't only something that is meant to be consumed by web services. Coming from a web programming background I can see where the confusion is, but any software with proper documentation for how to interact with its public functions or methods is considered to have an API.@mpql commented on GitHub (Mar 31, 2021):
I think this is the clearest view on this, considering how . I think SemVer can best be understood by assuming that you would document how to interact with your program, and update this documentation as necessary with changes that would change that interaction, based on how they would change it (BC bug fixes, BC functionality edition, NBC updates).
An API is the schema by which communication should happen with the program -- a CLI carries this out directly, as can a GUI. If any changes happen such that this schema should change, we change the version accordingly.
So... I would not personally say I've generally heard anyone declare that a GUI or a CLI is an API, but relative to measuring version increments, they come from roughly the same perspective here. If something about an argument (or its function) for a CLI changes, the API has changed and the documentation should be updated, so the version should be incremented. Likewise, if something changes in a GUI, the API can be said to have changed, because if you were programming something to interact with it, you'd have to check its behavior against that change.
I think the most actionable thing here is to define in-doc what an API is, and what we mean when we talk about changes to it, and what would necessitate them. I don't think we need to change any fundamental terminology, just clarify it so everyone's on the same page.
@designermonkey commented on GitHub (Apr 8, 2021):
I agree, as that was my intent in the initial issue:
I was pointing out semantics, and basically asking for a more clear explanation, as (and I don't want to stir the pot again) technically speaking it is currently wrong irrespective of common vernacular and assumption.
A simple terms or ubiquitous language near the top to explain that API is used and is synonymous with UI, CLI and API within the document.
@DomHudson commented on GitHub (Apr 8, 2021):
The way I've always understood it is that any software-to-software intermediatory is an API, so if a CLI is consumed by another software system then the CLI is an API.
Talking about GUIs rather confuses matters as they are not usually intended to be consumed by software and therefore aren't that relevant to semver. If you automated interaction with the GUI then the GUI acts as an API to you.
@StingyJack commented on GitHub (Jun 25, 2021):
Application Programming Interface
@designermonkey - when you start off a discussion for correctness with terminology and use an incorrect term, its going to be hard to win people over, especially a detail-oriented crowd like this. Please edit the OP so I can give you a thumbs up without also endorsing incorrectness.
@jwdonahue commented on GitHub (Dec 4, 2021):
From the introduction:
While the author was indeed focused on programming interfaces originally, specifically library and package interfaces, they gave it a very broad definition and non-traditional scope. Application Programming Interface is not generally taken to mean just documentation. It is an unfortunate side effect that the meaning of technical jargon tends to drift proportionally to the number of people who use the jargon. This is now amplified by sites like WikiPedia where anybody can add their own spin on anything.
@magjac commented on GitHub (Dec 4, 2021):
My interpretation of this has always been that the author with "This may consist of..." is referring to the declaration of the API, not the API itself. I therefore think that the term API can and should be interpreted as a programming interface and nothing else, although I'm aware that many commenters don't and ignore the
Pso I'm not going to argue about it.@jwdonahue commented on GitHub (Dec 4, 2021):
I long ago translated API to something akin to a contract, just to maintain my own sanity. If you think of it as a contract or promise implied or explicitly defined by the publisher, the whole spec is easier to generalize and makes a lot more sense when you consider that we really use SemVer mostly to version collections of interfaces, implementations and data.
@Cheddar77 commented on GitHub (Dec 23, 2021):
I love that it’s really amazing
@thom-jp commented on GitHub (Feb 12, 2022):
I was confused by the word API and took effort to find out whether I can apply semver or not. Then, I found discussion here.
I personally suppose that term "API" is mainly used for software friendly interface.
In broad range of word interpretation, we probably can claim as like "My GUI software versioning is comply with semver 2.0.0.", based on a thought that GUI can be used by software,
I think it's no problem of applying semver to your GUI software based on above perspective.
But yet I believe it is not a straight interpretation of majority that GUI is also API.
Hope there is more better alternative word.
(Sorry I have no idea for better English word as non-native speaker)
Anyway, as I'm not very sure the intention of original author, just in the case to avoid risk of my wrong interpretation, I'd like to claim "my versioning is Semantic Versioning like" in case I use 0.0.0 style.
@igorpupkinable commented on GitHub (May 3, 2022):
It is obvious that term API is vague and interpreted differently, which is OK because there is no standard with formal definition. Check out history of the term section to see the term evolving.
Since SemVer convention can be applied to virtually anything including Microwave panel or TV remote control, then usage of
public interfacemakes more sense.TV remote can have button removed: MAJOR change; button added: MINOR change; plastic buttons swapped to rubber ones: PATCH. You really can version TV remote controls at a factory, though TV remote has a public interface rather than an API.
@travnick commented on GitHub (Nov 13, 2023):
Putting my thoughts here.
@ljharb I see no reference to GUI in this text https://www.mulesoft.com/resources/api/what-is-an-api, this is all about software-to-software interactions.
I see no other definition or interpretation of an API than it's something that is usable in software-to-software interactions. It's clearly defined as programming interface.
@designermonkey, @ljharb
By definition, GUI is not and API, because it's user interface. I see no publications to support the definition of API "as the umbrella term" that includes the GUI and CLI as such in general.
On the other hand, with evolution of tools, one may decide that a GUI of his software act as an API by use of a specific tool for that purpose. So then in the context of abilities of that tool, you may document and call the GUI as the API.
The CLI is easier to be used as the API, but until documented as, it's not the API.
However, it's quite common to create a tool (as standalone, or an internal software functions) that act as API for the CLI. Anyway, you do it on your own risk.
So I can assume, that CLI or GUI may be treated as the API only when:
My final thought is, since I was also wondering if the semver applies to any GUI/CLI-only software, that it does not apply until you define the interface as an API. Since then, you will be able to tell what's a fix, new feature (but backward compatible), and introducing a breaking change and properly adjust the numbers.
@ljharb commented on GitHub (Nov 13, 2023):
Yes, it is, because programmers are users.
@travnick commented on GitHub (Nov 14, 2023):
@ljharb you mean GUI is an API because the programmers are users (in GUI)?
@jwdonahue commented on GitHub (Nov 14, 2023):
In some organizations, the test group are the first consumers of any product. Some of my first test automation was written solely for the purpose of verifying GUI correctness and performance. I also recall seeing a lot of screen scrappers back during the mainframe to mini transition (I worked on one).
From the SemVer intro:
So if I identify my CLI or GUI output as the "public API" that I intend to support, then I am keeping well within the spirit, and the letter; of the SemVer spec to apply SemVer style semantics to my CLI or GUI versioning scheme.
I am in complete agreement with @designermonkey wrt the definition of API in the SemVer document. It adds to the confusion and consternation around the SemVer spec, as is witnessed by the many threads and comments to that effect in this issues database.
Today, every one of the SemVer maintainers, represents a packaging tool or development silo. Their products are not used to version interfaces per-se, they are used to version collections of interfaces, implementations and data. There are however, dev silo's where interfaces, implementations and data are versioned separately, and in many cases they use SemVer or something very much like it.
The language around API in the intro, the spec and the FAQ, in no way limits what a creative person might apply SemVer to, but it has contributed to some confusion.
@StingyJack commented on GitHub (Nov 18, 2023):
Yeah, I do not get whey its even present. SemVer can be applied to so many things to address the unknowns of upgrading. API, GUI, Service, Component, Package, internal only, external/public, etc. - all of these things and more benefit from using version numbering that means something easily understood instead of using version numbering that is arbitrary and tells the user nothing.
@knarrff commented on GitHub (May 30, 2025):
I am not sure why people get into so many arguments: the document clearly says: the first thing you need to do is to define your API. If your API includes a CLI or even a GUI, then you define it like that and that's it. If you don't, then it means you don't intent users to use the CLI or GUI as a software-software interface, since it's not part of your API.
In other words: SemVer does not need to define if CLI or GUI are part of "the API": it's the job of the maintainer to do that, and it may differ between two different pieces of software.
@malachycrossan commented on GitHub (Jun 3, 2025):
If my anecdote is worth anything, I am a relatively inexperienced developer and I was confused by the term API in this documentation. It was only curiousity and insomnia that brought me to this thread. After reading through it, I understand how the word was supposed to be interpreted. However, my initial understanding was that a GUI interface did not "count" as an API.
I have a couple points. Let me know if I am off-base about any of them:
@jwdonahue commented on GitHub (Jun 8, 2025):
Perhaps, but any non-normative language preceding or following the actual spec, will cause confusion in somebody's mind and lead to endless threads regarding what it means. It's hard enough to convince some people, that what the spec says, is what it means, and nothing else.
I've never seen a GUI that could not be interacted with, programmatically. It's far more likely that a change to a GUI, will break somebody's test code, than say, the average implementation change behind an API.
Confusion in the mind, not the text. It is language, therefore someone will always be confused by it. That said, I have always thought the preamble could be improved, but I don't like some of the proposed fixes, even more. Therein lies the problem. Tighten up the language, and some will interpret it as imposing additional restrictions, which some will like, and others will not.