APIs The Right Way
by Eshwar Natarajan in Apps/DevOps, General
APIs are one of the most important aspect of a fully functioning end product, especially, when you are extensively working on Mobile Apps and you would want to have right process in place to ensure success of the project. A well-designed API should have following features:
- Platform Independence: Any client should be able to call the API, regardless of the internals of the API.
- Service Evolution: You should be able to evolve and add functionality while existing applications should continue to function without modification.
Just like real-world construction, APIs are foundation of your product and cutting corners will have disastrous outcome.
Introducing Swagger for RESTful APIs
We started using Swagger almost an year back and figured out that we were not only able to build APIs quickly but also ensure that it is easier to debug and maintain them. Swagger provides a common framework and powerful but easy to use tools that take full advantage of the OpenAPI specifications.
OpenAPI leverages the definition-driven approach and requires you to start building API’s business logic and detailing the exact request and responses that your API end-points will expose.
Here is how we do it the right way:
Step 1: Design
The quickest way of getting started with the OpenAPI specification is to use Swagger Editor to design, define and document the RESTful API. The specifications are visually rendered and besides that, the editor interacts with the API even while you are defining it. It does on-the-fly specification validation and provides instant feedback.
Step 2: Develop
Swagger helps you jump start here by providing Codegen, an open source tool, that allows you to quickly prototype APIs by generating boilerplate code.
Typically our projects are based on Python using the flask-restful REST implementation with the SQLAlchemy ORM and Swagger Codegen works out beautifully for us.
Step 3: Verify
Make sure you test your APIs for bugs and defects. You can use Swagger Inspector that quickly validates your API.
Step 4: Document
Don’t let your fantastic creation ruined by poor documentation. Let’s admit that documentation can be boring and hard to do.
Use Swagger UI to produce beautiful visual documentation and make it easier for back-end implementation and client-side consumption. Be precise about what the API does and how it works.
Step 5: Release
If you have followed all the previous steps, you have done a great job in creating something on a robust foundation that works and is well documented. You are now ready to roll out your creation.
Are you ready?
Checkout Swagger and Swagger Petstore for an example.