Problem
Our department was splitting into domain-focused sub-teams in preparation of adopting Agile SCRUM. Future projects would require cross-team collaboration, and previous projects had faltered when it came to designing services for consumption by eachother. Cross-team stand-ups had helped, but an important bottleneck was our contract design – it was happening in text documents and presentations. We needed a modern way of designing and iterating on APIs, to parallelise work and provide clarity to clients and test engineers.
Solution
I did some research into API-first design – creating a framework for data interchange prior to implementation. A company called SmartBear had developed a RESTful API documentation tool we had used in the past, but at the time “Swagger” had muddied our controller classes. Now some years on, they provide SaaS solutions for collaborative API design, hinging on an open-source specification format written in JSON/YML: the “Open API“. This specification is more than declarative; it can be used for code-generation, auto-mocking, and loaded into REST clients like Postman.
I established a relationship with SmartBear, and built a proof-of-concept integration with our Maven-Bitbucket pipeline that would automatically POST documentation to SwaggerHub. I ran training talks on the specification, and used this API-first process in the next project that required a RESTful API to great success – client developers were able to interrogate the input and output models ahead-of-time, leading to no last-minute changes. The philosophies underpinning this way of working have since been adopted by our “tech principles”, and continue to help us design better services.
Learning
- Creating relationships with external developers
- Evaluating and comparing different software solutions
- API design & development
- Delivering training
