API definition for powerful Web APIs
The right API description language is critical to the future success of your interfaces.
August 12, 2019 | 4 Min.Anyone involved in the planning, design and development of API interfaces will sooner or later have to deal with the API definition and one of the popular description languages.
A good API is characterized above all by positive quality characteristics. First and foremost, this includes clear consistency, the easiest possible usability and a suitable abstraction.
The importance of a helpful documentation should be ensured from the beginning and must never be underestimated. As soon as the API is to be made available to other developers, it is imperative to document as detailed and comprehensive an API definition and description as possible.
A powerful Web API is only successful if its structure is well represented. Technical specifications such as end points offered, HTTP methods and parameters used, and how requests should look are essential. All these specifications ensure good usability and, if formulated appropriately, also support automatic code generation.
The description language used to create an API definition is left to the developer. Here we highlight the most common languages like Open API, Swagger and RAML.
Open API
Under the leadership of the Linux Foundation, a special working group called the "Open-API Initiative" was founded in 2015. At the same time, Swagger was taken over by SmartBear - the tool manufacturer of the well-known and respected SoapUI.
Both steps led to the renaming of Swagger to the Open-API Specification (OAS) under the aspect of remaining manufacturer-neutral.
In the meantime 26 members such as Adobe, SAP, PayPal, eBay, Google, MuleSoft and also Microsoft belong to it. The consistent further development takes place on GitHub and opens thereby the participation in the project to any interested party through issues or pull requests.
In mid-2017, version 3.0 of Open-API was approved and published. Compared to the previous version 2.0, a clearer structure could be achieved especially on the top level of the hosts and security. Another big step forward was made in supporting the JSON scheme. Based on the formats JSON or YAML 1.2 different languages like Java, JScript, .Net, Ruby, Scala or Gitlab can be used.
Also in Open-API the starting points Contract-/API-First or alternatively the program code via Code-First exist. A detailed description of Open API can be found in our practical article Open API Specification.
Swagger
The Swagger API project was launched by Tony Tam in 2011. In today’s highly networked business world, it is increasingly important to allow distributed applications to communicate with central servers via API interfaces.
For a long time, APIs were preferably described using the WSDL (Web Service Description Language). Probably the biggest disadvantage is the technical implementation of REST interfaces.
One of the biggest advantages of Swagger, however, is the language-neutral and machine-readable format, which is usually defined with JSON or YAML. In addition, it offers a powerful extension mechanism.
Swagger also has the IDL (Interface Definition Language) for simplified programming of RESTful interfaces. In addition, Swagger supports both Code-First and Contract-/API-First development.
Various tools such as the core library (swagger-core), the visualization interface (swagger-UI), a powerful editor (swagger-Editor) and the code generator (swagger-Codegen) make it easy to develop and test powerful interfaces.
As part of the description Swagger Tooling can be used. Based on the source code, a complete documentation can be generated automatically. A much more detailed description of Swagger can be found in our article Swagger.
RAML
What started with Swagger as a quasi-standard for REST-based applications has been more clearly structured and extended with the Open-API specification.
However, there is no standard for the description of a REST API, but SOAP-based Web services have always been described by WSDL documents.
With RAML (RESTful API Modeling Language) another important tool for API First Development is now available. The requirement for a uniform description of REST API’s is not really new.
An API definition usually includes the following contents such as entry points, resource paths, GET/PUT methods with parameters, business objects, types and error codes.
Mulesoft’s developers summarized the necessity and advantages of the API definition in the modern RAML description language. They benefit greatly from many predecessors such as WADL and Swagger.
An API description is provided in YAML file format. This makes it very easy to read due to its simplified notation, on the one hand, and on the other, even complex hierarchies can be represented very well. An accompanying documentation can also be given over several chapters. Query parameters can be defined for individual methods and can also be used as so-called "traits" in other methods. Details and possible applications for RAML can be found in our TECH article RAML.
Conclusion
The description languages listed here have a solid basis and many followers. Swagger is the quasi-standard for REST-based API definitions due to its wide distribution and tool support. RAML is a technically modern and lightweight description language that provides various tools for API modeling. The Open API Specification is based on Swagger and introduces clearer structures and meaningful extensions and will probably establish itself as the new standard in the long term.