I'm trying to understand what they really are, but I can't understand how to use them.

MAJOR version when you make incompatible API changes.

What is incompatible API changes?

MINOR version when you add functionality/features.

Examples of a new functionality or features?

Sorry for the noob question.

  • 5
    Take a look at semantic-versioning for examples. Also semver.org Commented Apr 23, 2023 at 15:01
  • 1
    You don't know what "functionality/features" for an API means? Well, can you please give an example for an API you have worked with, so answerers can give you an explanation using that example?
    – Doc Brown
    Commented Apr 23, 2023 at 18:53
  • Realistically, major means the number before the dot and minor means the number after the dot. Commented Apr 24, 2023 at 13:54

2 Answers 2


Assuming that you are using Semantic Versioning, then the definitions of "major" and "minor" come from that specification. Other versioning schemes may use the terms differently than Semantic Versioning does.

An incompatible API change means that something in the interface has changed in a way that would break the interactions with clients. It could mean adding required arguments to a method or endpoint, changing the types and structures of data returned, or removing a method. Any client who uses a method with these incompatible changes needs to update their code to handle the new interface appropriately.

There are several minor changes that aren't incompatible. Adding a new method or endpoint, for example, provides new functionality to clients without changing any existing interactions. Marking a method as deprecated also doesn't change any existing interactions and can provide information to people calling the API that a future major version will cause significant changes to how they interact with the API. In a minor update, clients are not required to take immediate action, but may choose to take steps to use the new or modified functionality.


An incompatible change is a change that would cause existing clients of the API to stop working correctly unless they are updated to match the API changes.

Let's say the API has a function called GetBook(string) which returns a book based on its title. If this function is renamed or removed in an update, existing clients which use this function will just stop working. More subtly, if the semantics of the function is changed to interpret the string argument as an ISBN number, then it would also mean existing clients stop working correctly. So both these changes would be breaking changes and merit a major version bump.

But if a new function GetBookByAuthor(string) is added, but the existing function is unchanged, this will not cause any error, so this merit a minor version upgrade.

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