API first - Process for internal services
By
Ailton SilvaView All Posts
Passionate about technology, music and playing guitar. A big fan of New Balance sneakers.
Top Stories
1 - API first - Process for internal services2 - Accelerating Software Development with Chassis Pattern
Overview
FARFETCH is a dynamic and agile company with constant changes - it has a large number of teams, a microservices architecture where each team is responsible for a set of services, and each service could have several consumers.In this scenario, how can we ensure that the constant changes in services do not affect or even make consumers stop working?
With that in mind, the API first model for internal services is being adopted, with a central point where each service has an OpenAPI specification containing every description of what it provides. The idea is that every change needs to be designed and reviewed before being implemented.
Benefits
It is expected that having a single point where the process of design, validation, and review of the internal APIs are done will lead us to:- Improvements in quality and consistency;
- Reducing the number of incidents due to breaking changes;
- Breaking change detection and consumers notifications;
- Enabling faster feedback using tools to:
- Validate automatically rules, versioning, and retro compatibility;
- Mock generation with OpenAPI specifications;
- Increasing productivity with the adoption of code generation;
- Removing the diamond dependency problem;
- Having "a big picture” of all internal API’s.
How does it work?
There is a monorepo with folders split by domain areas and each team is responsible to submit their services specifications. The repository structure is described in Figure 1 below
Figure 1 - Repository Structure
Once a new specification is submitted or something changes, a pipeline runs and a validation flow starts. The validation flow is described in Figure 2 below:
The pipeline validates automatically:
Once a breaking change occurs, a bot will add a comment in the merge request tagging the consumers of the service so that they can become aware of the changes, and have the chance to share questions or possible issues that can affect their applications.
Figure 2 - Validation Flow
The pipeline validates automatically:
- Version: It checks if the version follows the semver convention, and also if the version was incremented. When a spec has changes, the validation tool will require the version incrementation
- Rules: It checks if the endpoints, components, and properties are following the internal rules related to:
- Nomenclature
- Path versioning
- Return types
- Status codes
- Changes: It validates the new version against the previously approved version and checks that the changes don’t cause any breaking changes.
Intentional breaking changes
There are situations where changes are necessary even if it will cause breaking changes to the consumers. In these cases it is possible to submit intentional changes by adding a line to the breaking-change file with the version and description of the change, you can see the complete flow in Figure 2 above.Once a breaking change occurs, a bot will add a comment in the merge request tagging the consumers of the service so that they can become aware of the changes, and have the chance to share questions or possible issues that can affect their applications.
