diff --git a/README.md b/README.md index 062ac16e..2ae79289 100644 --- a/README.md +++ b/README.md @@ -33,11 +33,11 @@ A list of some of the frequently accessed documents that are an output of the wo |-------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [API-design-guidelines.md](documentation/API-design-guidelines.md) | This document captures guidelines for the API design in CAMARA project. These guidelines are applicable to every API to be worked out under the CAMARA initiative. | | [API-DocumentationTemplate.md](documentation/API-DocumentationTemplate.md) | Template for documenting the APIs | -| [API-Readiness-Checklist.md](documentation/API-Readiness-Checklist.md) | A checklist that describes the minimum criteria for considering an API Ready | -| [Camara_Versioning_Guidelines.md](documentation/Camara_Versioning_Guidelines.md) | Guidelines for API Subprojects on making releases | | [Glossary.md](documentation/Glossary.md) | A glossary of the common terms and their API parameter/field names for use in the APIs | | [API-Testing-Guidelines.md](documentation/API-Testing-Guidelines.md) | Guidelines for the API testing in CAMARA project | +NOTE: Guidelines for Release Management of API versions, e.g. the API-Readiness-Checklist, are located within [ReleaseManagement](https://github.com/camaraproject/ReleaseManagement). The versioning of APIs is defined within the [API-design-guidelines.md](documentation/API-design-guidelines.md#5-versioning). + ## Status and released versions diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7644f5ec..293d0d95 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -27,8 +27,10 @@ This document captures guidelines for the API design in CAMARA project. These gu - [4.1 URL Definition](#41-url-definition) - [4.2 Input/Output Resource Definition](#42-inputoutput-resource-definition) - [5. Versioning](#5-versioning) - - [5.1 Versioning Strategy](#51-versioning-strategy) - - [5.2 Backwards and Forward Compatibility](#52-backwards-and-forward-compatibility) + - [5.1 API version (OAS info object)](#51-api-version-oas-info-object) + - [5.2 API version in URL (OAS servers object)](#52-api-version-in-url-oas-servers-object) + - [5.3 API versions throughout the release process](#53-api-versions-throughout-the-release-process) + - [5.4 Backward and forward compatibility](#54-backward-and-forward-compatibility) - [6. Error Responses](#6-error-responses) - [7. Common Data Types](#7-common-data-types) - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) @@ -537,78 +539,134 @@ These considerations are below: ## 5. Versioning -### 5.1 Versioning Strategy +Versioning is a practice by which, when a change occurs in the API, a new version of that API is created. -Service versioning is a practice by which, when a change occurs in the API of a service, a new version of that service is released so that the new version and the previous one coexists for a certain period of time. +API versions use a numbering scheme in the format: `x.y.z` -Consumers will be migrated to the new version of the service sequentially. When everyone is consuming the latest version of the service, the previous version is removed. +* x, y and z are numbers corresponding to MAJOR, MINOR and PATCH versions. +* MAJOR, MINOR and PATCH refer to the types of changes made to an API through its evolution. +* Depending on the change type, the corresponding number is incremented. +* This is defined in the [Semantic Versioning 2.0.0 (semver.org)](https://semver.org/) standard. -Consumers can distinguish between one version of the service and another, the technique of adding the API version to the context of the base URL will be used, since this technique is the most used in the main reference APIs. +### 5.1 API version (OAS info object) -The structure of the URL would have the following form: -```http -https://host:port/api/v1/resource +The API version is defined in the `version` field (in the `info` object) of the OAS definition file of an API.  + +```yaml +info: + title: Number Verification + description: text describing the API + version: 2.2.0   + ... ``` +In line with Semantic Versioning 2.0.0, the API with MAJOR.MINOR.PATCH version number, increments as follows: -When we version through the URL, only the "MAJOR version" is included since this would change when a change incompatible with the previous version occurs. +1. The MAJOR version when an incompatible / breaking API change is introduced +2. The MINOR version when functionality is added that is backwards compatible +3. The PATCH version when backward compatible bugs are fixed -API implementation versioning will follow semantic versioning. Given a `MAJOR.MINOR.PATCH` version number, it increments: -1) The `MAJOR` version when you make an incompatible API change. -2) The `MINOR` version when you add functionality that is backwards compatible. -3) The `PATCH` version when you fix backward compatible bugs. +For more details on MAJOR, MINOR and PATCH versions, and how to evolve API versions, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the CAMARA wiki.  -Related to the versioning of rest parts involved in Apification projects, best practises are detailed below: +It is recommended to avoid breaking backward compatibility unless strictly necessary: new versions should be backwards compatible with previous versions. More information on how to avoid breaking changes can be found below. -SHARED CODE ON REPOSITORIES +### 5.2 API version in URL (OAS servers object) -1) MAJOR - Major of API Contract -2) MINOR - Minor of API Contract -3) PATCH - New Updates / Contributions of shared code +The OAS file also defines the API version used in the URL of the API (in the `servers` object). -MICROSERVICE DEPLOYMENTS (NOT MANDATORY BUT RECOMMENDED) +The API version in the `url` field only includes the "x" (MAJOR version) number of the API version as follows: + +```yaml +servers: +    url: {apiRoot}/qod/v2 +``` -1) MAJOR - Major of API Contract -2) MINOR - Minor of API Contract -3) PATCH - New Microservice Deployments +--- + +IMPORTANT: CAMARA public APIs with x=0 (`v0.x.y`) MUST use both the MAJOR and the MINOR version number separated by a dot (".") in the API version in the `url` field: `v0.y`. + +--- + +```yaml +servers: +    url: {apiRoot}/number-verification/v0.3 +``` +This allows for both test and commercial usage of initial API versions as they are evolving rapidly, e.g. `/qod/v0.10alpha1`, `/qod/v0.10rc1`, or `/qod/v0.10`. However, it should be acknowledged that any initial API version may change. -### 5.2 Backwards and Forward Compatibility +### 5.3 API versions throughout the release process -Avoid breaking backwards compatibility unless strictly necessary, that means, new versions should be compatible with previous versions. +In preparation for its public release, an API will go through various intermediate versions indicated by version extensions: alpha and release-candidate. + +Overall, an API can have any of the following versions: + +* work-in-progress (`wip`) API versions used during the development of an API before the first pre-release or in between pre-releases. Such API versions cannot be released and are not usable by API consumers. +* alpha (`x.y.z-alpha.m`) API versions (with extensions) for CAMARA internal API rapid development purposes +* release-candidate (`x.y.z-rc.n`) API versions (with extensions) for CAMARA internal API release bug fixing purposes +* public (`x.y.z`) API versions for usage in commercial contexts. These API versions only have API version number x.y.z (semver 2.0), no extension. Public APIs can have one of two maturity states (used in release management):  + * initial - indicating that the API is still not fully stable (x=0) + * stable - indicate that the API has reached a certain level of maturity (x>0) + +The following table gives the values of the API version (Info object) and the API version in the URL as used in the different API version types created during the API release process. For public API versions, this information is also dependent on whether it is an initial (x=0) or a stable public API version (x>0). + +| API version type | API version | initial (x=0) API version in URL | stable (x>0) API version in URL | API version can be released | +|---------------|:------:|:------:|:------:|:------:| +| work-in-progress | wip | vwip | vwip | No | +| alpha | x.y.z-alpha.m | v0.yalpham | vxalpham |Yes (internal pre-release) | +| release-candidate | x.y.z-rc.n | v0.yrcn | vxrcn | Yes (internal pre-release) | +| public | x.y.z | v0.y | vx | Yes | + +Precedence examples: + +* 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0. +* 0.1.0 < 0.2.0-alpha.1 < 0.2.0-alpha.2 < 0.2.0-rc.1 < 0.2.0-rc.2 < 0.2.0 (initial public API version) +* 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (stable public API version) + +For more information, please see [API versioning](https://wiki.camaraproject.org/x/a4BaAQ) in the Release Management project Wiki. + +### 5.4 Backward and forward compatibility + +Avoid breaking backward compatibility, unless strictly necessary, means that new versions should be compatible with previous versions. Bearing in mind that APIs are continually evolving and certain operations will no longer be supported, the following considerations must be taken into account: -- Agree to discontinue an API with consumers. +- Agree to discontinue an API version with consumers. - Establish the obsolescence of the API in a reasonable period (6 months). - Monitor the use of deprecated APIs. - Remove deprecated APIs documentation. - Never start using already deprecated APIs. +Types of modification: - Types of modification +- Not all API changes have an impact on API consumers. These are referred to as backward compatible changes. +- In case of such changes, the update produces a new API version that increases the MINOR or PATCH version number. +- The update can be deployed transparently as it does not change the endpoint of the API which only contains the MAJOR version number which has not changed, and all previously existing behaviour shall be the same. +- API consumers shall be notified of the new version availability so that they can take it into account. -Not all API changes have an impact on API consumers. These changes are often referred to as backward compatible changes. If the API undergoes changes of this type, it should not be necessary to release a new version, it will suffice to replace the current one. What would be very convenient is to notify our consumers with the new changes so that they take them into account. +Backward compatible changes to an API that **DO NOT** affect consumers: -This is a list of changes to an API that **DO NOT** affect consumers: +- Adding a new endpoint +- Adding new operations on a resource (`PUT`, `POST`, ...). +- Adding optional input parameters to requests on existing resources. For example, adding a new filter parameter in a GET on a collection of resources. +- Changing an input parameter from mandatory to optional. For example: when creating a resource, a property of said resource that was previously mandatory becomes optional. +- Adding new properties in the representation of a resource returned by the server. For example, adding a new age field to a Person resource, which originally was made up of nationality and name. -- Add new operations to the service. Translated to REST, it would be to add new actions on a resource (`PUT`, `POST`, ...). -- Add optional input parameters to requests on existing resources. For example, adding a new filter parameter in a GET on a collection of resources. -- Modify input parameters from required to optional. For example: when creating a resource, a property of said resource that was previously mandatory becomes optional. -- Add new properties in the representation of a resource returned by the server. For example, adding a new age field to a Person resource, which originally was made up of nationality and name. +Breaking changes to an API that **DO** affect consumers: -This other list shows changes that **DO** affect consumers: -- Delete operations or actions on a resource. For example: POST requests on a resource are no longer accepted. -- Add new mandatory input parameters. For example: now, to register a resource, a new required field must be sent in the body of the request. -- Modify input parameters from optional to mandatory. For example: when creating a Person resource, the age field, which was previously optional, is now mandatory. -- Modify a parameter in existing operations (resource verbs). Also applicable to parameter removal. For example, when consulting a resource, a certain field is no longer returned. Another example: a field that was previously a string is now numeric. -- Add new responses to existing operations. For example: creating a resource can return a 412 response code. +- Deleting operations or actions on a resource. For example: POST requests on a resource are no longer accepted. +- Adding new mandatory input parameters. For example: now, to register a resource, a new required field must be sent in the body of the request. +- Modifying or removing an endpoint (breaks existing queries) +- Changing input parameters from optional to mandatory. For example: when creating a Person resource, the age field, which was previously optional, is now mandatory. +- Modifying or removing a mandatory parameter in existing operations (resource verbs). For example, when consulting a resource, a certain field is no longer returned. Another example: a field that was previously a string is now numeric. +- Modifying or adding new responses to existing operations. For example: creating a resource can return a 412 response code. - Compatibility management +Compatibility management: -Tho ensure this compatibility, the following must be followed. +To ensure this compatibility, the following guidelines must be applied. -**As API producer**: +**As API provider**: +- Never change an endpoint name; instead, add a new one and mark the original one for deprecation in a MINOR change and remove it in a later MAJOR change (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality) +- If possible, do the same for attributes - New fields should always be added as optional. - Postel's Law: “Be conservative in what you do, be liberal in what you accept from others”. When you have input fields that need to be removed, mark them as unused, so they can be ignored. - Do not change the field’s semantics. @@ -617,6 +675,10 @@ Tho ensure this compatibility, the following must be followed. - If you use collections that can be returned with no content, then answer with an empty collection and not null. - Layout pagination support from the start. +Make the information available: +- provide an access to the new API version definition file (via a link or dedicated endpoint) +- if possible, do the same to obtain the currently implemented API version definition file + **As API consumer**: - Tolerant reader: if it does not recognize a field when faced with a response from a service, do not process it, but record it through the log (or resend it if applicable). - Ignore fields with null values. diff --git a/documentation/Camara_Versioning_Guidelines.md b/documentation/Camara_Versioning_Guidelines.md deleted file mode 100644 index c4c66111..00000000 --- a/documentation/Camara_Versioning_Guidelines.md +++ /dev/null @@ -1,28 +0,0 @@ -# Camara subproject release guidelines - -* Release name for subprojects should be same as the tag-name for e.g. v0.8.0. The GitHub [release feature](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) should be used for this purpose. If referenced outside the subproject, it can be referred to as Release **\\** for e.g. Release QualityOnDemand v0.8.0 -* Every release includes the **CHANGELOG.md** file in the root directory of the subproject. Please make sure that the content is structured in a format that is easy to read. Please refer to the template provided here for possible sections that could be added to a changelog [CHANGELOG_TEMPLATE.md](./SupportingDocuments/CHANGELOG_TEMPLATE.md). Every release would add to the changelog. An example of how a changelog could look over time is shown below. -* The release can be agreed within the subproject by making a pull request for the changelog. The merge of this pull request would be marked as the release commit and the text within the changelog would be used as the release description -* Changelog content: - * APIs/Software in alpha release needs to be clearly specified - * API changes (This should include/cover all API objects which are part of the API bundle) - * New features - * Fixes - * Deprecation (if any) -* Going ahead, we could decide on a pull request process where use of right PR annotations could allow us to use tooling such as [krel](https://github.com/kubernetes/release/blob/master/docs/krel/README.md) or similar to automate at least parts of release management. -* Release branches should have naming convention **release-x.y.z** -* Release tags should follow the naming conventions vx.y.z for versions -* Adding relevant annotations to tags will be useful for later reference. -* Provider implementation repos can have their own naming conventions with regard to branches, tags etc. It is however mandatory to provide as a part of the  CHANGELOG.md - the API release version, capabilities and changes that are a part of the respective provider implementation release. -* Main branch is assumed to be the latest. -* Camara subproject will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release of any given subproject within Camara. -* The commonalities WG does not impose any restrictions on the subprojects for creating other branches, tags which might be needed/useful to address their specific requirements. The above said guidelines are only applicable for the subproject releases. -* Main (`main`) branch and all release branches (`release\*`) will be protected by branch rules in GitHub: All pull requests need to be reviewed by at least one code owner before they can be merged - -### Release branches -Ver - -### Changelog -Changelog