As we continue to build on the number of APIs currently in service we provide a central repository for all of the specificactions that have been agreed. The Swagger documentation provides a concise view of the various endpoints of our APIs and how to use them. Our API specifications document our journey to establishing how the APIs were designed and the many decisions that were taken. This will give us the opportunity to learn from our past choices and continue to build and improve as we go.
Some people may wonder why we have decided to publish our design specifications. What we have discovered is that, in a rapidly developing environment there needs to be a way to keep track of changes and the decisions behind those changes. By publishing our specifications we facilitate:
- Learning - the specifications are a quick reference point on how we design the various APIs
- Onboarding - a quick way to get colleagues up to speed on the design/development process
- Continuous collaboration - as technology evolves and as we get new points of view there is always the opportunity to revisit our designs and improve on them. Our specs should be where this all kicks off.
We are always looking at ways we can improve. If you have any ideas or suggestions please share your feedback on our Specifications GitHub Repo.