An Introduction To OpenAPI

(Image: eCollect®)
(Image: eCollect®)

Specification and framework

The OpenAPI specification is mainly centred on descriptions of paths (endpoints/URLs), operations (GET, UPDATE) and objects (data) that are forming the API conversation. All these definitions are typed in JSON or YAML as a convenient storage for processing by OpenAPI development tools. The programmer starts with the top-level endpoints defining a list of allowed actions (operations) and the URL parameters available for these operations. Each operation would return a response (payload), which is usually in some web-friendly format such as JSON. The response media though is not limited — it could be anything. The specification is very flexible and many different responses for a single operation can be described. In the response body definition, we can specify a customised object type (even sets of different object types depending on the operation completion state).

Importance of tools

No matter how good a specification is — it is as good as the tools and the development framework which are to make use of it. It is where the Swagger team made a very good effort to provide the two most important tools: a definition editor and a code generator.

Wide adoption and future

Every new technology is as good as the problems it can solve. The challenge to define a proper and structured API exchange application protocol is a significant part of the cloud- and web-based server applications, as well as their consumer counterparts — websites, mobile apps, and other cloud services.

  • Openness to other well-established technologies and standards — like the JSON, HTTP and authentication models used by the specification
  • Tooling and utility development — how much of the developer’s community would engage in creating more and more facilitation for the specification to live on
  • Vision and evolution factors — it is hard to measure the impact of those, especially when sometimes it is a matter of personal programmer’s opinion if some specification/framework is good or not, but it is a fact that some software technologies live longer, while other quickly fade-out
  • Support and community — it is not possible for a specification to survive if it is not extensively used in many software systems, especially ones created by big teams and maintained for long periods of time

Europe’s leading receivables management platform

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store