What does "public api" means in Semantic Versioning?

Question

I'm learning about how to assign and increment version numbers with the rule called "Semantic Versioning" from http://semver.org/.

Among all its rules, the first one said:

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive"

I am confused about "public API". What does it refer to?

Answer 1

Public API refers to the "point of access" that the external world (users, other programs and/or programmers, etc) have to your software.

E.g., if you're developing a library, the public API is the set of all the methods invokations that can be made to your library.

There is understanding that, unless a major version changes, your API will be backwards-compatible, i.e. all the calls that were valid on a version will be valid on a later version. You can read at point 9 of those rules:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

Answer 2

I discovered SemVer today and read up on it from several sources to ensure I had fully grasped it.

I am confused about "public API". What does it refer to?

I was also confused about this. I wanted to set about using SemVer immediately to version some of my scripts, but they didn't have a public API and it wasn't even clear to me how they could have one.

The best answer I found is one that explains:

SemVer is explicitly not for versioning all code. It's only for code that has a public API.

Using SemVer to version the wrong software is an all too common source of frustration. SemVer can't version software that doesn't declare a public API.

Software that declare a public API include libraries and command line applications. Software that don't declare a public API include many games and websites. Consider a blog; unlike a library, it has no public API. Other pieces of software cannot access it programmatically. As such, the concept of backward compatibility doesn't apply to a blog. As we'll explain, semver version numbers depend on backward compatibility. Because of this dependence, semver can't version software like blogs.

Source: What Software Can SemVer Version?

Answer 3

It requires a public API in order to effectively apply it's versioning pattern.

For example:

Bug fixes not affecting the API increment the patch version

Backwards compatible API additions/changes increment the minor version, and...

Backwards incompatible API changes increment the major version.

What represents your API is subjective, as they even state in the SemVer doc:

This may consist of documentation or be enforced by the code itself.