What are API schemas?

This is a guest post for the Computer Weekly Developer Network written by David Brown in his position as CEO of Toro Cloud — the company is known for its low-code API-centric approach to application development, integration and workflow automation.

Brown’s full title for this API schemas analysis and explanation is:

What are API schemas… and how connectorless approaches to API development are proving the way forward.

He asks us to think back and remember when you used to start an application development project with the design of a database schema? So what does that initial schema scheme mean for APIs in the world of cloud?

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.

Content Continues Below

Join the conversation


Send me notifications when other members comment.

Please create a username to comment.

Would lower pricing and licensing costs entice you to switch hypervisors?
when the cost is anywhere from 5x-15x more with VMware, it’s irresponsible to not evaluate alternatives. we did exactly that and dropped VMware almost two years ago for hyperv & haven’t looked back
No question that licensing costs matter especially after being screwed multiple releases in a row by VMware. They broke our trust. As for opex, we’re a MS shop anyway so migrating won’t be overnight, but we’ll do it
Open to anything to reduce my datacenter costs.
Of course. Management is always telling us to reduce cost and licensing costs are very real.
Yes cost matters
Migration &Operational costs also needs to be considered.
If you build your environment with an eye toward possible switching, then switching is not a major pain anymore.
We used to be a VMware shop. We gradually converted to hyperv with the R2 release and it worked well. With the money we saved from retiring vmw we bought a new rack of servers and a san. None of this happened overnight but it was well worth the shiny new kit. we've been testing ws2012 since beta and we'll be moving to that as soon as it ships.
The Soft cost for switching Hypervisor will be astronomical, I am not just talking CapEx, but OppEx. things like retraining, too stability. different VM formats etc
Yes for small to medium.
ALL hypervisor tech is simply way too costly. In fact, the gov't (at my location) is considering dumping virtualization altogether and returning to physical servers. Sure the cost (electric/AC etc) is higher. Certainly, the footprint is a little larger, but space and capacity do exist AND physical servers are BY FAR more cost effective. Think HP/AIX and even Solaris (not so much) virtualization technologies.
We're on VSphere 5 it's the best & I wouldn't consider Microsoft to host our Virtual infrastructure.