Design First approach to microservice APIs
Rating: 10 out of 10
IncentivizedUse Cases and Deployment Scope
We use SwaggerHub to design our micro service APIs prior to development starting. Our Solution Architect's and Technical Business Analysts are able to collaborate and define the APIs based off user stories. Our Swagger API definitions are a core part of our customer facing documentation, so we put a lot of effort into that design phase to make sure we have consistent naming standards and have great descriptions and examples for each endpoint. Our customers can read our API documentation to understand what each API does, and they can also import the Swagger definitions and code stubs into their IDEs to give them a head start on the development process.
Pros
- Treating the design as documentation ensures that we have consistent and well defined APIs
- API consumers can export the swagger definition or code stubs to use within their development environment
- We can iterate through multiple versions of a definition privately before making a version publicly available
Cons
- Under the Swagger 2.0 standards you can only provide one example for each endpoint. A complex /search endpoint is a great use case for having multiple examples.
- Not able to define events that will be created or consumed by an API.
Likelihood to Recommend
SwaggerHub is perfectly suited for defining an API before development starts.
Vetted Review
3 years of experience