Advantages of API Specification
There are a few requirements when developing an API. It has to work correctly, be well specified (documented), and properly described. When following this advice, API will deliver significant benefits to multiple targets — users, developers, managers etc.
API Users
If there is an unspecified resource, it is time consuming to use it. It is obvious that you as an API user will not want to waste your time on reverse engineering. You will rather opt for an alternative API that is well specified and described.
API Developers
As a developer of the particular API, you can argue that everything you need can be found in the code. Well, it is true. However, will you remember without any written specification details such as data structure that is accepted and returned by the particular resource? Maybe for a short period of time it is not a problem, but how about in a few days, weeks or even months? The same situation occurs in a case of integration tests. Writing tests against documentation is better and faster with a good specification that looks directly into the code, switching between classes, resource models, etc.
Many can claim that specification would become obsolete after some time. To avoid this, they would have to be updating it every time the API is changed, and this would take time. Luckily, it is not how it works. Thanks to various open source projects that can be found, for example, on GitHub, we have access to multiple popular and widely used libraries for automatic generation of the specification. These libraries are also frequently used for the most popular specification frameworks nowadays, Swagger and ApiBlueprint.
There is another way that gives the specification a very powerful advantage. If you have a specification that has been created in a well-defined way, you can use it to generate a client to communicate with this API. In this way you can avoid manual rewriting which is error-prone and a time consuming task. This comes especially handy if you have an API with dozens of resources.
Let’s sum up the advantages of API specification:
- Your API is documented. This allows other developers to use your resources in a simple way.
- Your API can be read not only by developers. Because docs are mostly generated into webpage, it is readable for architects, managers or those who do not know (or do not want to know) what request query argument or content-type header is.
- Developers or testers can write tests in a simpler way because the specification is well and clearly readable.
- API client is generated for your application so there is no need for manual creation.
As we wanted to make the definition of resources as simple as possible, Apiwatcher tool supports import of resources from the following specifications:
- Swagger 1.2
- Swagger 2.0
- ApiBlueprint
This means that if you have an API specification, you can just copy/paste it into the Apiwatcher tool and all requests will automatically be generated for you.
There is only one important note — it is in beta now.
