The pain of designing and visualizing APIs and how to solve it
In Today’s software industry APIs play a major role. Be it for internal use or for exposing your services to the out side world; the key to a well designed software lies in well designed APIs.
The way APIs are being developed in many organizations today is problematic. Either they directly jump into implementing the APIs without a proper design or most of the organizations have multiple teams/developers working on API development and soon APIs tend to develop their own personality and become radically different form one another.
The one key solution that could fix the above issues is to design your APIs before starting to implement. Having a well designed set of APIs will mean faster time to market as developers wont have to reinvent the wheel every time they develop a new API or consume one. This will also make developers a lot happier (Amen to that).
There are 2 major players who can help you design you APIs
- Open API Specification (formerly Swagger)
Swagger follows a bottom-up approach for designing APIs. You implement you API, use Swagger libraries and it will generate your API design and a beautiful documentation. But this is not what we are looking for. We want something that will help us design our APIs even before implementing.
On the Other hand RAML follows top-down approach. Mulesoft provides a set of tools that help you design your API and visualize it in human friendly representations.
The issue with both of them is that you and your team need to know the specifics and syntax of both the description languages. What if there was something available to design your APIs that is not tightly coupled with these design languages and provide a tool to design API on the fly without knowing any of the design language syntax. Enter APIC — The complete API solution.
APIC consists of 3 main modules:
- API Designer
- API Tester
- API Docs
For creating a well planned API design, APIC’s API design is the person of interest. The designer tool provides a simplistic UI where you can easily define your API. Using the UI you can define request headers, request parameters, response types and their respective schema.
The designer provides a tool to design JSON schema on the fly. With the Schema designer you can define all possible response codes for you API endpoint and their respective response schema.