Once you have published a specific version of an API or Lightning Component (that has been declared as visible outside of your package), do not change its definition, for example, Custom Objects; Fields; Apex classes, methods, or members; equivalent REST or SOAP constructs; or component attributes. Even though the platform will help avoid certain changes, additions can be considered a breaking change, especially new required fields. Anything that changes the definition or signature of the API can be considered a potential breaking change.

Developer X should be able to modify and redeploy their existing integrations or extensions without having to recode or adjust their code using your API and without forcing them to upgrade to the latest version of your API, unless, of course, they want to access new functionality only accessible by completing new fields. Note that this is different from upgrading the package itself within the subscriber org, which must be allowed to happen.

The standard Salesforce APIs and platform help provide versioning when Developer X interacts with your Custom Objects and Application APIs. Versioning is implemented as follows:

• In an Apex code context, the platform retains the version of your package installed when the Apex code was first written by Developer X, and then only ensures that Apex classes, methods, members, Custom Objects, and fields visible in that packaged version are visible to the code. This feature is something that we will explore in further detail later in this chapter.
• In the case of the SOAP and REST APIs, by default, the latest version of your Custom Objects is visible. When using the SOAP API, header values can be passed in such calls to lock a particular package version if needed (search for PackageVersionHeader in Apex Developer's Guide). Alternatively, the packaged version used by these APIs can be set at an org-configuration level.