API Specifications & Architecture

An application programming interface (API) defines how applications communicate with one another. The term API describes any interface. For this article and the ones to follow I will refer to Web APIs as an API.

A web API defines an interface through which applications access resources. These resources can be in the cloud, the local network, or an enterprise.

The design of these APIs has become exceedingly critical. As more companies embark on their digital transformation journey. In fact, I would argue that the most important pillar of a successful transformation is the design of the API. It helps application developers write better applications and ensures the business can incorporate changes, and a lot more.

There are as many API design styles as there are APIs themselves. Over the years I’ve seen three major designs that have had great adoption:

• REST: The oldest of the lot. It defines a set of stateless operations which demand resources as a response.
• JSON API: JSON is a widely used message format but it doesn’t have a fixed structure. You can create the same JSON message, formatted in several ways. JSON API is a specification that enforces messages to adhere to a format.
• GraphQL: GraphQL is facebook’s data query and manipulation language.

It’s important to note that these standards were defined at different times. They are all great and solved problems that were important at the time of their invention.

Selecting an API specification is important and sometimes can be biased. To make this decision easy I’ve created a set of criteria and graded each design type on it.

GraphQL not only supports most of the above criteria but was also designed to work in a mobile-first world. The primary mode of usage has changed from desktops to mobiles and will further change. It’s important to be able to build applications to meet the user where s/he is.

GraphQL has a rich set of libraries for all client frameworks which allows for rapid application development. Libraries such as apollo allow you to build offline-first applications and a lot more. Several cloud providers now provide GraphQL services to build APIs. What REST did to API design GraphQL might do to all APIs in general. It has become the dominant API specification.

Where to go from here

Companies on the path of a transformation should choose GraphQL as an API specification. The ability to build clients that can query for the exact data they need is very powerful. Businesses can build a slew of applications on different platforms with one API.

This was the first article in this multi-part series. In the next article we’ll write about under and over-fetching.

By Ali Hafizji

Originally appeared on https://www.wednesday.is/writing-articles/api-specifications-architecture