What are API schemas?

Brown writes as follows…

Let’s go back to basics and remind ourselves that a database schema is a collection of metadata that defines the relationships between tables, fields, objects and information found within a database. The schema helps define a database, acting as a guide to help programmers properly navigate their way through tables, views, procedures and more.

Now think of an API. An API is an interface that allows two disparate chunks of software, services, or platforms to transact with each other through a request-response message system.

How convenient would it be for developers if they had the equivalent of a database schema for an API? 

Various industry bodies have been working on standardising application integration since the 90s when web services were introduced. The SOAP protocol was an attempt to create some standards for working with web services.

Lessons learned from SOAP

For a while, Simple Object Access Protocol (SOAP) was considered the ‘god’ of messaging protocol for web services. Its operation and input parameters were documented in a schema called a Web Service Definition Language (WSDL).

Over time, it became harder to work with a web service without a WSDL, making it almost like a prerequisite for SOAP. However, over the years, SOAP became increasingly verbose making its use more burdensome.

As the quest for faster, lighter, and better web-based apps emerged, developers turned to the REST architecture to address these issues from SOAP.

REST stands for REpresentational State Transfer. It is very much the architecture behind designing networked applications. REST relies on a stateless communications protocol, such as HTTP.

Because of this, REST is easier to use, more flexible, and a lot faster, making it a very attractive option for APIs. RESTful APIs (which are web services that implement REST) are widely seen as the lean saviour for loosely coupled systems.

The birth of the API schema

Making your API discoverable means ensuring it is well documented with code snippets and SDKs. What was missing from REST was machine-readable documentation – like how WSDL is for SOAP.

The need to define and describe APIs led to competing API Description Languages (API DL) such as RAML, Blueprint, and Swagger.

Thus, the API schema was born.

API DLs produce an API schema, which is both human and machine-readable.

An API schema works by describing the operations of a RESTful API and the methods on how to interact with an API – just like a virtual instruction manual that helps amplify programming processes.

The schema not only allows an API to be more discoverable and easier to use, but with a well-defined API schema, developers can also create machine-generated API documentation and client SDKs.

When OpenAPI went to war with API DL

With the number of API DLs growing, industry heavyweights rallied behind the establishment of a new open standard known as OpenAPI after the Swagger specification was donated to the OpenAPI Initiative.

My programme leverages the use of an API schema to interface with an API directly via its Integration Platform as a Service (iPaaS) called Martini.

I was looking to solve a significant problem for developers. Previously, when you wanted to use an iPaaS to integrate with an API, you were reliant on the vendor of that iPaaS to provide a connector. If your vendor didn’t offer a connector for the API you wanted to integrate, then your options were fairly limited. Likewise, when the API changes, you had to wait for the vendor to update the connector.

My company’s software’s support for OpenAPI allows it to ingest the machine-readable API schema and generate the services on the fly that are required to consume any operation from the API.

The integration platform can consume, publish and manage APIs without requiring connectors.

Why schema definition is needed

REST was introduced as a lightweight solution to address the burdens of SOAP. However, it turns out that a RESTful API needs a schema to define the contract and make it more discoverable.

Modern application development relies heavily on integration with APIs. As developers begin the process of writing code for their APIs, they need the equivalent of a database schema to accurately identify the design of their web service – and the API schema serves exactly that purpose.

Toro CEO Brown: Support for OpenAPI allows you to ingest machine-readable API schema and generate services on the fly.