[GH-ISSUE #541] Change wording "public api" to reduce confusion #7372

New Issue

GiteaMirror · 2026-06-20T17:24:00-05:00

GiteaMirror commented

2026-06-20 17:24:00 -05:00

Originally created by @binyamin on GitHub (Dec 4, 2019).
Original GitHub issue: https://github.com/semver/semver/issues/541

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation....

Source: https://semver.org/#spec-item-1

Request

Change Public API to something else.
Or
Define the term Public API

Reason
Most developers think of the term API as referring to code, ie, programmatically accessible endpoints on a web server.

It seems from both the wording of the SemVer specs (...or exist strictly in documentation....) and the issues and questions (see #453, #468, stack overflow) which have been raised regarding the term, that the generally understood definition is not the indented meaning.

While the term may be used correctly in the specs, it does not convey the clarity for which documentation and specifications aim.

Originally created by @binyamin on GitHub (Dec 4, 2019). Original GitHub issue: https://github.com/semver/semver/issues/541 > 1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation.... > ><cite>Source: <https://semver.org/#spec-item-1></cite> **Request** - Change <q cite="https://semver.org/#spec-item-1">Public API</q> to something else. Or - Define the term *Public API* **Reason** Most developers think of the term API as referring to code, ie, programmatically accessible endpoints on a web server. It seems from both the wording of the SemVer specs (<q cite="https://semver.org/#spec-item-1">...or exist strictly in documentation....</q>) and the issues and questions (see #453, #468, [stack overflow](https://stackoverflow.com/questions/9463613/what-does-public-api-means-in-semantic-versioning)) which have been raised regarding the term, that the generally understood definition is not the indented meaning. While the term may be used correctly in the specs, it does not convey the clarity for which documentation and specifications aim.

GiteaMirror closed this issue

2026-06-20 17:24:00 -05:00

GiteaMirror commented

2026-06-20 17:24:02 -05:00

@runeimp commented on GitHub (Dec 5, 2019):

@b3u API is a general term in programming. It's not specific to the web in any way. And is meant to be very generic. Those links have a huge amount of discussion on the topic for a reason. The concept is (in general) simple but the range of implementations is massive and most of them have many different factors that need consideration regarding their own concept of a Public API. This makes documentation that works for every single case next to impossible. But if you have some clever way to summarize the incredible diversity of factors that need to be considered to construe and embody the scope of what a Public API is in every given scenario then please share those ideas. But, unfortunately, I can pretty much guarantee you that simply changing the wording "Public API" to something else is going to be just as confusing (if not more so) than what already exists. Also restating that there is confusion about something, and citing massive discussion talking about the confusion on the platform that is home to most of those discussions, and not providing any concrete suggestions after years of work has already gone into the docs is not helpful. The authors of the spec are aware of the limitations of the doc and have not made a call for input or help to improve the docs beyond what was cited. Please either add your own concrete ideas or close this issue.

I, for one, am grateful the authors created the SemVer spec and have put as much time into maintaining and improving the spec as they have. They are generous and rather accepting of ideas and discussions that have merit. If you have real ideas please share them. Everyone would love to see more clarification in the docs. If you don't, then why are you posting this?

@runeimp commented on GitHub (Dec 5, 2019): @b3u API is a general term in programming. It's not specific to the web in any way. And is meant to be very generic. Those links have a huge amount of discussion on the topic for a reason. The concept is (in general) simple but the range of implementations is massive and most of them have many different factors that need consideration regarding their own concept of a Public API. This makes documentation that works for every single case next to impossible. But if you have some clever way to summarize the incredible diversity of factors that need to be considered to construe and embody the scope of what a Public API is in every given scenario then please share those ideas. But, unfortunately, I can pretty much guarantee you that simply changing the wording "Public API" to something else is going to be just as confusing (if not more so) than what already exists. Also **restating** that there is confusion about something, and citing massive discussion talking about the confusion on the platform that is home to most of those discussions, and not providing any concrete suggestions after years of work has already gone into the docs is not helpful. The authors of the spec are aware of the limitations of the doc and have not made a call for input or help to improve the docs beyond what was cited. Please either add your own concrete ideas or close this issue. I, for one, am grateful the authors created the SemVer spec and have put as much time into maintaining and improving the spec as they have. They are generous and rather accepting of ideas and discussions that have merit. If you have real ideas please share them. Everyone would love to see more clarification in the docs. If you don't, then why are you posting this?

GiteaMirror commented

2026-06-20 17:24:03 -05:00

@binyamin commented on GitHub (Dec 5, 2019):

@runeimp I apologize for any offense I may have given.

I can't give an alternative, because I myself have no idea what the term "Public API" means in this circumstance. If you can point me to an explanation, I would love to draft a proposal for the docs.

@binyamin commented on GitHub (Dec 5, 2019): @runeimp I apologize for any offense I may have given. I can't give an alternative, because I myself have no idea what the term "Public API" means in this circumstance. If you can point me to an explanation, I would love to draft a proposal for the docs.

GiteaMirror commented

2026-06-20 17:24:04 -05:00

@ljharb commented on GitHub (Dec 5, 2019):

API stands for "application programming interface" - it's "how you interact with the thing from code". It likely includes (but may not include all of):

exposed export/class/function/method/property names
when exceptions are thrown
what function/method/constructor arguments are required vs optional
what semantics/behavior everything has under every scenario
allowed platform versions, whether explicitly or implicitly
dependencies that are required to be explicitly provided (in npm's case, these are "peer dependencies")

This is not an exhaustive list.

@ljharb commented on GitHub (Dec 5, 2019): API stands for "application programming interface" - it's "how you interact with the thing from code". It likely includes (but may not include all of): - exposed export/class/function/method/property names - when exceptions are thrown - what function/method/constructor arguments are required vs optional - what semantics/behavior everything has under every scenario - allowed platform versions, whether explicitly or implicitly - dependencies that are required to be explicitly provided (in npm's case, these are "peer dependencies") This is not an exhaustive list.

GiteaMirror commented

2026-06-20 17:24:04 -05:00

@sungam3r commented on GitHub (Dec 5, 2019):

Even message format, encoding, byte order, etc. may be considered as a part of public api.

@sungam3r commented on GitHub (Dec 5, 2019): Even message format, encoding, byte order, etc. may be considered as a part of public api.

GiteaMirror commented

2026-06-20 17:24:05 -05:00

@binyamin commented on GitHub (Dec 5, 2019):

Thank you

@binyamin commented on GitHub (Dec 5, 2019): Thank you

GiteaMirror commented

2026-06-20 17:24:05 -05:00

@runeimp commented on GitHub (Dec 11, 2019):

@b3u I'm sorry but your post makes me angry. I'm almost certainly over reacting and I don't know why. I quite well remember my own confusion when I originally started learning programming and concepts such as API, OOP, MVC, and the rest of the alphabet soup programmers deal with regularly. And not knowing why your post strikes such a chord with me frustrates me even more.

Thank you for your apology. It is appreciated but unnecessary as you were obviously not malicious in your post. You are a better person than I for extending it. I wish to extend my own apology as my response was heavy handed and that was unwarranted. I'm sorry.

@runeimp commented on GitHub (Dec 11, 2019): @b3u I'm sorry but your post makes me angry. I'm almost certainly over reacting and I don't know why. I quite well remember my own confusion when I originally started learning programming and concepts such as API, OOP, MVC, and the rest of the alphabet soup programmers deal with regularly. And not knowing why your post strikes such a chord with me frustrates me even more. Thank you for your apology. It is appreciated but unnecessary as you were obviously not malicious in your post. You are a better person than I for extending it. I wish to extend my own apology as my response was heavy handed and that was unwarranted. I'm sorry.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#7372