As with any industry, the web API space faces different approaches to standardization. Not least of which are the differences between how API providers choose to define their APIs in a machine readable way with API specifications and description languages.
API definitions have emerged as ways to annotate API functionalities, and there are still many out there catering to varying web service architectures. Read more
In our recent post on tips for starting a public API journey we touched briefly on the idea of creating a style guide that helps API providers produce well-constructed and consistent APIs as part of their public API offering. The creation of an API style guide is, however relevant for API providers regardless of whether they are providing APIs externally or internally: It provides the context for their development efforts whether it be outsourced or created internally and is an important tool for achieving some level of governance across the organization. Read more
The most common API definition languages we spot in the wild are Swagger / OpenAPI Spec, RAML and API Blueprint. All three let you define your endpoints, your resources, your query or path parameters, your headers, status codes, security schemes, and more. Read more
Whilst many aspects of the API economy are subject to discussion and conjecture, if there is one truth it’s this: When it comes to successfully describing your API, the jury is out on the best tool for the job. As the API economy has grown so has the number of API description specifications, each with their own specific format and supporting tools. Read more