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:
Update API documentation in GitBook as well as in GitHub
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
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.
Notify testing and sandbox teams, as well as other BB leads
Post messages in Slack in the #testing, #sandbox, and #technical-committee channels, outlining the changes and linking to the updated API specifications
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.
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:
Import the existing API definition either from a URL or by uploading a json or yaml file
Update or add any new APIs
Validate to ensure that there are no errors in the API definitions or schema
Export the API as a yaml file
Upload changes to the Building Block GitHub repository (/api directory)
Update API definitions in GitBook