Code first approach
- Backend developers write the code,
- Hand the code over to the Testers,
- The Documentation team (Developers and Technical writers) writes the docs,
- The Review team reviews it.
- Takes too much time for the reviewers
- Very expensive to change
- Teams don’t have much time to change the code nor the documentation
- Not efficient
API First approach
Parallel and synchronous team work
The Developer, Tester, Documentation, and Delivery teams work together and synchronously under the guidance of a Product Manager, who knows exactly what the customer needs.
- Decision makers
- Link the teams together
- Give feedback from the customers
The work starts with writing the API specification: the development bends before the design.
API First roadmap with OpenAPI 3.0 Specification
OpenAPI 3.0 Specification is human-friendly, and machine-readable
- Increases efficiency: teams can work in parallel using a flexible architecture.
- Opens up opportunities for automation (CI/CD): automated testing, documentation, and some degree of code-generation.
- Increases the usability for end-users: the documentation can help the customers to understand the API.
API First workflow
The workflow happens through a centrally managed tooling package, architected for easy switching to new tools.
1. Development cycle
- writing the API specification,
- sending the pull requests,
- doing the team review.
- linting (with open-source tools like Spectral) – the linter can run locally,
- generating and using mock-servers (with open-source tools like Prism or APIsprout) – they can run locally and remotely,
- merging to the repository after the Review team approved.
Result: API specification
To get an API specification at the very beginning
- Brainstorming, idea-sharing between the product manager, the customer, other stakeholders, testers, and developers
- The result is the API specification
- Very manual work, but open-source tools can help generating and editing the API specification
2. Continuous integration layer
Manual work: none
- Mock server started
- Client code generated
- Documentation generated
- Server code generated
3. Development cycle continues
- Manual work:
- Testers/Pre-sales: don’t have to wait until the real logic comes out – they can use the mock server and the generated client code
- Technical writers: can edit the generated documentation – they can provide early feedback for the developers
- Developers: write the code, add the logic
- Testers: can test the code and the functionality
- Review team: does a final review after the code passed the tests
- Automatic work:
- Code committing
- Contract testing to check whether documentation matches with the code
- Publishing the API
- Result: Published API