[GH-ISSUE #331] The term "API" is unnecessarily limiting #5356

New Issue

GiteaMirror · 2026-06-15T11:41:09-05:00

GiteaMirror commented

2026-06-15 11:41:09 -05:00

Originally created by @israel-lugo on GitHub (Sep 20, 2016).
Original GitHub issue: https://github.com/semver/semver/issues/331

I believe that the term "API" is too limiting in scope.

I think it is more or less understood by the reader that SemVer uses the term "API" in a broad sense. For me at least, I read it as an interface contract.

I would suggest replacing mentions of "API" with "Interface", or something that means "the full interaction with the program".

"API" maps directly to projects such as a library, which will be used by other programs. However, SemVer also makes sense in other contexts, where there isn't necessarily an actual Application/Programmer relationship.

Issues #314 or #311 are good examples of what I mean. To quote myself from the former:

For me, it makes perfect sense e.g. for a CLI tool to use SemVer. As a human user, I am supposed to interact with the program, i.e. by using the --foo option to enable Fooing and the --bar=5 option to limit Bars to 5. If a new version of the program no longer allows you to Foo (the --foo option is gone), then I would say that is a "breaking change in the API".

Even in a graphical program, SemVer can make perfect sense. The program can have a new button, a new dialog box, a new feature ("you can now put text in bold"). The program can have a bugfix, or a feature removed ("exporting to PDF is no longer supported").

SemVer makes sense for any project that is interacted with, whether it be by a program or by a human user. The consumer of the project expects a certain set of features, and for those features to work in a specific manner. This works whether the consumer is a program, a script, a library, a human being or a dog.

Heck, this would work even if the project is a toaster oven ;)

Originally created by @israel-lugo on GitHub (Sep 20, 2016). Original GitHub issue: https://github.com/semver/semver/issues/331 I believe that the term "API" is too limiting in scope. I think it is more or less understood by the reader that SemVer uses the term "API" in a broad sense. For me at least, I read it as an _interface contract_. I would suggest replacing mentions of "API" with "Interface", or something that means "the full interaction with the program". "API" maps directly to projects such as a library, which will be used by other programs. However, SemVer also makes sense in other contexts, where there isn't necessarily an actual Application/Programmer relationship. Issues #314 or #311 are good examples of what I mean. To quote myself from the former: > For me, it makes perfect sense e.g. for a CLI tool to use SemVer. As a human user, I am supposed to interact with the program, i.e. by using the --foo option to enable Fooing and the --bar=5 option to limit Bars to 5. If a new version of the program no longer allows you to Foo (the --foo option is gone), then I would say that is a "breaking change in the API". Even in a graphical program, SemVer can make perfect sense. The program can have a new button, a new dialog box, a new feature ("you can now put text in **bold**"). The program can have a bugfix, or a feature removed ("exporting to PDF is no longer supported"). SemVer makes sense for any project that is interacted with, whether it be by a program or by a human user. The consumer of the project expects a certain set of features, and for those features to work in a specific manner. This works whether the consumer is a program, a script, a library, a human being or a dog. Heck, this would work even if the project is a toaster oven ;)

GiteaMirror closed this issue

2026-06-15 11:41:10 -05:00

GiteaMirror commented

2026-06-15 11:41:11 -05:00

@zafarkhaja commented on GitHub (Sep 20, 2016):

Heck, this would work even if the project is a toaster oven ;)

This would work only if you were programmed to use only a single version of a toaster oven at home and there was a toaster oven repository you could use to downgrade a newer version in the office :)

@zafarkhaja commented on GitHub (Sep 20, 2016): > Heck, this would work even if the project is a toaster oven ;) This would work only if you were programmed to use only a single version of a toaster oven at home and there was a toaster oven repository you could use to downgrade a newer version in the office :)

GiteaMirror commented

2026-06-15 11:41:11 -05:00

@BurtHarris commented on GitHub (Sep 21, 2016):

The words used in the spec are even more "limiting" than you say, with good reason. It specifically it says semantic versioning applies to the "public API." A software package may have one or more private or unstable interfaces, that may be subject to breaking changes without requiring a Semver major version change.

Lets say you try to apply Semver to a CLI of a tool, and the tool's author corrects the spelling of an error message. Is that a breaking change? I don't think the concept applies applies (especially if the public API uses error numbers or exit codes which remain stable.) Another example of a private interface: the format of a verbose log file. If we over-broaden the definition of Semver, it could actually weaken it for purposes it was originally conceived, by creating too many judgment calls.

@BurtHarris commented on GitHub (Sep 21, 2016): The words used in the spec are even more "limiting" than you say, with good reason. It specifically it says semantic versioning applies to the "**public** API." A software package may have one or more private or unstable interfaces, that may be subject to breaking changes **without** requiring a Semver major version change. Lets say you try to apply Semver to a CLI of a tool, and the tool's author corrects the spelling of an error message. Is that a breaking change? I don't think the concept applies applies (especially if the public API uses error numbers or exit codes which remain stable.) Another example of a private interface: the format of a verbose log file. If we over-broaden the _definition_ of Semver, it could actually weaken it for purposes it was originally conceived, by creating too many judgment calls.

GiteaMirror commented

2026-06-15 11:41:13 -05:00

@ameenross commented on GitHub (Oct 13, 2016):

@BurtHarris I immediately think of the HTTP referer header, which basically was never fixed because it would result in backward compatibility breakage. However, field content (in this example, an error message) is not the same as a field name.

What's often the case for error messages is that there is an error code, which is part of the API and guaranteed to stay the same, and a message, which is often used to display the error to users, but is not defined to be part of the API. Or rather, the API specifies that there is a message, but these aren't suitable to do string comparisons on. A program interacting with these errors should always uses the code. Therefore, when a spelling mistake is fixed in an error message, it won't result in a backward compatibility breaking change, whether in the case of an API or of a CLI (where there's $? exit status). IMO it would be just like any other bugfix.

Also consider that error messages could be localised.

@ameenross commented on GitHub (Oct 13, 2016): @BurtHarris I immediately think of the [HTTP referer](https://en.wikipedia.org/wiki/HTTP_referer) header, which basically was never fixed because it would result in backward compatibility breakage. However, field **content** (in this example, an error message) is not the same as a field **name**. What's often the case for error messages is that there is an error _code_, which is part of the API and guaranteed to stay the same, and a _message_, which is often used to display the error to users, but is not defined to be part of the API. Or rather, the API specifies that there is a message, but these aren't suitable to do string comparisons on. A program interacting with these errors should always uses the _code_. Therefore, when a spelling mistake is fixed in an error _message_, it won't result in a backward compatibility breaking change, whether in the case of an API or of a CLI (where there's `$?` exit status). IMO it would be just like any other bugfix. Also consider that error messages could be localised.

GiteaMirror commented

2026-06-15 11:41:13 -05:00

@emperorz commented on GitHub (Oct 23, 2016):

API is okay, it is absolutely the public interface contract. Over define the language and it will get very very messy, and ironically, not open to extension. For example "public". There's a tricky word. "Semantic" also fails. I'd rather leave it a little fuzzy, and avoid semiotic hell, thanks. Please close "will not fix"

@emperorz commented on GitHub (Oct 23, 2016): API is okay, it is absolutely the public interface contract. Over define the language and it will get very very messy, and ironically, not open to extension. For example "public". There's a tricky word. "Semantic" also fails. I'd rather leave it a little fuzzy, and avoid semiotic hell, thanks. Please close "will not fix"

GiteaMirror commented

2026-06-15 11:41:14 -05:00

@peteroupc commented on GitHub (Jan 10, 2017):

What @israel-lugo probably has in mind too is consumer-facing applications (rather than merely developer-facing applications) with a graphical user interface, especially networking client applications. This covers both traditional desktop programs and those for mobile devices which are available on the App Store, Google Play Store, etc.

@peteroupc commented on GitHub (Jan 10, 2017): What @israel-lugo probably has in mind too is consumer-facing applications (rather than merely _developer-facing_ applications) with a graphical user interface, especially networking client applications. This covers both traditional desktop programs and those for mobile devices which are available on the App Store, Google Play Store, etc.

GiteaMirror commented

2026-06-15 11:41:14 -05:00

@FichteFoll commented on GitHub (Jan 10, 2017):

The issue with end-user facing software is that it's hard to impossible to properly define standards for UI design that are a minor or a major change. As such, semver is generally not designed for these types of applications but you can still infer your very own versioning from it.

@FichteFoll commented on GitHub (Jan 10, 2017): The issue with end-user facing software is that it's hard to impossible to properly define standards for UI design that are a minor or a major change. As such, semver is generally not designed for these types of applications but you can still infer your very own versioning from it.

GiteaMirror commented

2026-06-15 11:41:16 -05:00

@jwdonahue commented on GitHub (Oct 9, 2018):

@israel-lugo

I've tried to consolidate all of the "API should be changed X" and similar issues into #468. Please contribute to this discussion on that thread and close this one at your earliest possible convenience.

Thank you.

@jwdonahue commented on GitHub (Oct 9, 2018): @israel-lugo I've tried to consolidate all of the "API should be changed X" and similar issues into #468. Please contribute to this discussion on that thread and close this one at your earliest possible convenience. Thank you.

GiteaMirror commented

2026-06-15 11:41:16 -05:00

@alexandrtovmach commented on GitHub (Jun 10, 2020):

Closed in favor #468

@alexandrtovmach commented on GitHub (Jun 10, 2020): Closed in favor #468

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#5356