Documenting API Changes

As Building Block specifications change, there will be inevitable changes to the APIs that are defined for a Building Block. When APIs change, the BB leads should take the following steps to ensure that all teams are aware of these changes and can update their work accordingly:

1. Update API documentation in GitBook as well as in GitHub

   1. API changes should be submitted as a PR in GitHub, with updates to the OpenAPI/Swagger definitions. An architecture team member will review and approve these changes

   2. The API definitions in GitBook should be updated to reflect the changes. Note, the API definitions can be pulled in directly from the OpenAPI/Swagger definitions in GitHub.

2. Notify testing and sandbox teams, as well as other BB leads

   1. Post messages in Slack in the #testing, #sandbox, and #technical-committee channels, outlining the changes and linking to the updated API specifications

3. Support the testing and sandbox teams and respond to any questions/requests they have as they implement new tests and functionalities to support the API changes.

4. Keep a changelog of API changes, specifically marking any breaking changes. This changelog will be submitted to the Product Owner as a part of release notes for this BB for each release.

Note, except where urgently required, API changes will only be published as a part of a release.

Tools for API Development

For creating and validating changes to APIs, we recommend using the Swagger Next API editor that can be found here: https://editor-next.swagger.io/

The process for using this tool is:

1. Import the existing API definition either from a URL or by uploading a json or yaml file

2. Update or add any new APIs

3. Validate to ensure that there are no errors in the API definitions or schema

4. Export the API as a yaml file

5. Upload changes to the Building Block GitHub repository (/api directory)

6. Update API definitions in GitBook