Declaration of module APIs: Public and private

According to Semantic Versioning, we release a major version of a module when there are backward compatibility (BC) breaking changes in the Public API. This document declares what public and private APIs are.

Public API

In the Spryker Commerce OS’s core, the following is the public API:

• Public methods in these locatable classes:

  • Facades
  • Clients
  • Query Containers
  • Services

• Interfaces:

  • Plugin interfaces
  • Plugins

• Other classes:

  • Module Config Client/Yves/Zed/Shared/Service
  • Controllers
  • Twig functions
  • CLI commands
  • Public constants that define environment configuration in Constant Interfaces

• Database

• Search

• Storage

• Transfer objects

• Glossary keys

BC breaking changes

There are several classes and files which are part of the public API, but not every change in the file causes a BC break. In general, 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.

We always try to avoid breaking changes of BC and reduce the effort needed to upgrade a module to a new version. There are several ways to add functionality to APIs without a BC break. So you can add new methods and even parameters to the existing methods as long as they are optional.

Private API

The public API term is introduced by Semantic Versioning. To refer to everything that is not part of the public API in Spryker Commerce OS, we introduced a private API.