Definition of Module API

Edit on GitHub

According to Semantic Versioning, Spryker releases a major version “when there are incompatible API changes”. To make a sound decision about the version type, we need to define our internal APIs.

In the Spryker Commerce OS’s core, all public methods in theses locatable classes are considered as API:

And the interfaces which are implemented everywhere are also part of the API:

  • Plugin interfaces
  • Plugins

In addition to these obvious cases, there are some other classes that are part of the API and can cause a BC break:

Every change in a schema can cause a BC break:

There are several other ways to cause a BC break:

  • A new major version of an open-source component that is embedded in the Spryker Commerce OS.
  • A new glossary key in the existing business logic (because there is no translation in the project).
  • The whole software design is part of the API. These modules are marked as Engine. For example, it would be a global BC break if we would enforce another structure of Twig templates for all modules or require another directory structure for modules or change a method in the abstract controller.

Not parts of the API are all module-internal classes are instantiated by factories. Although they have public methods, they are not intended to be used from the project code.

BC Breaking changes

As described above, there are several classes and files which are part of the API. But not every change there would cause a BC break. In general, we can say: there is a BC break whenever an existing contract is changed. A contract is what the user of the API expects. This includes the signature of methods as well as the expected behavior. For this reason, we have added an ApiDoc to the most used APIs like facades and plugin interfaces.

In any case, Spryker Commerce OS’s core team wants to avoid BC breaking changes and reduce the effort needed in projects to use a new version of a module. There are several ways to add functionality to APIs without a BC break. So it is possible to add new methods and even parameters to the existing methods as long as they are optional.