With the number of published and private APIs growing exponentially in the last few years, the need for standardization of describing, documenting and testing APIs has become more urgent.
At BinaryOps.io we have two major use cases for API Definition standards: outbound and inbound.
We have settled on Swagger for that purpose, primarily for the interactive user interface that comes along with the documentation. There are also other benefits for our users. Swagger has a lot of uptake, for instance you can generate client side code for many platforms using the swagger json file.
This file is not really an API definition. Instead it is a subset of the API definition, that we use to build out the complete API.
The BinaryOps.io service definition file format is less about defining end points, with methods, parameters and response codes. Rather, it is about specifying resources by type, including security constraints. Each resource type comes with a pre-defined set of end points, each with it’s own set of methods, parameters and responses. Resource types are ‘Entities’, ‘Queries’ and will soon include ‘File System’, ‘Notification’ etc. Having all of that complexity pre-packaged, consistent and tested is exactly why you want to use the BinaryOps.io back-end. It let’s you focus on your functionality, without having to re-invent the wheel.
Hopefully, a standard like Swagger, RAML or API Blueprint will evolve to include the use case of the inbound Service Definition file. It would greatly improve the shareability of hosted backend services.