3

from semver.org:

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.

Why are we forced to declare a public API? Why can't I use it for my own website that has no API?

Perhaps I am wrong with the definition. For me it is a part of the site desigedn for other developers (i.e.: api.example.com) that allow them to query my website and get the result into structured data (json, xml...).

2
  • They're not talking about web service APIs. They're talking about the actual code.
    – Doval
    May 14, 2014 at 19:41
  • Technically every website has a public API: its web pages. We maybe don't think of websites this way, but it is how users interact with what is, essentially, the code of the website. If you change the layout of your website, or some of the pages are made unavailable, then the public API has changed. Oct 18, 2022 at 12:41

3 Answers 3

10

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.

I think that is where your misunderstanding is. An API is not necessarily...

a part of the site designed for other developers that allow them to query my website and get the result into structured data

It could be that. Who knows. It could also be a set of documented UX rules.

If you can't effectively outline what your website's API is, then maybe SemVer isn't appropriate.

4
  • So if my website is just coded for me I don't need semantic versionning if I understand
    – Vinz243
    May 14, 2014 at 19:58
  • That is completely possible.
    – BrandonV
    May 14, 2014 at 19:59
  • I apologize for being stupid, but their is no I interest in using semantic versionning for me? Also, where should I put the versionning if there is a public api as described ? For the whole website or just for the part?
    – Vinz243
    May 14, 2014 at 20:04
  • 2
    These are all "it depends" type questions. We don't know enough about your use case to say "this doesn't make sense for you". All we can say is "this may not make sense". When versioning a web-service, it is common to use path parameters as ''/api/v2/people/42''. If you're talking about language specific APIs / libraries, the versioning really depends on the framework and implementation (Java, PHP, C#).
    – BrandonV
    May 14, 2014 at 20:07
4

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

Why are we forced to declare a public API? Why can't I use it for my own website that has no API?

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?

0

Semantic versioning is intended to remove the arbitrariness that can be seen when someone decides to select a versioning scheme for their project. To do that, it needs rules, and a public API is a rule that SemVer chose to use. If you are building a personal project, you don't need to follow SemVer, or follow it strictly. You can, for example, choose to loosely interpret is as

  • MAJOR: Big new feature or major refactor
  • MINOR: New feature which does not impact the rest of the code much
  • PATCH: Small bug fix

But the vagueness of this loose interpretation opens you up to arbitrariness again. That might not matter to you, or the people you foresee who will be using your software.

The larger your project is, the more the details of your versioning scheme matters. As someone who has worked in a third level support for a large IT company (which licenses APIs to customers) for quite some time, I have seen the "is it a bug or is it a feature" debate many times. SemVer intends to make such distinctions easier.

A public API can, of course, be a REST API, or the public interface of a software library. The public/private distinction is important, because one should have the freedom to change the private code without it adversely affecting other people. (If someone accesses your private code through, say, reflection, and you make a change which breaks their code, that is their loss.)

But a public API can even be something like command line switches. Think of POSIX compliant CLI tools. These tools are standalone applications. But they are used in shell scripts, so the input they accept, and the output they produce, can matter. The GNU project may choose to reimplement a POSIX standard tool, and include its own features, but in order for a plethora of shell scripts to continue working across different systems, they need to maintain the behaviour of the existing switches for that application. I have seen people having to build wrappers around applications because the output of the version command changes, and they had scripts relying on the output of the version command to be in a certain form. Should the output of the version command be part of the public API, or is what those people using it did a hack? The answer is that it is up to you and what guarantees you make to the people using your software. You might not be able to imagine all use cases. Declaring the intended use of your software creates a contract with your users, which is what a public API is.

SemVer, thus, makes it easier for your uses to know what they are getting when upgrading. Did only the patch level change? Yes, so better install it quick to get the latest patch fix. Did the major version change? Better run a full, potentially expensive, regression test suite to see if my application will still work after the upgrade.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.