I work or have worked with APIs of all sorts of standards, sometimes many standards at once – or none. Each standard exists for a purpose and might be a great fit, or a terrible fit for other purposes. Today’s post is a recap of some of the common API standards around and what you need to know about each one.

Why do APIs and open standards matter? APIs are the way that machines exchange information. They are the engines that drive connected software. Without APIs, we’d be waiting for a nightly CSV download or parsing data from PDFs. Using open standards gives us established patterns to follow, so that the data can be easily transferred and understood. The familiar formats make APIs easier for humans, and very very much easier for machines.

Of course, there isn’t a single standard (and there’s an XKCD for that), so let’s take a quick look at some of the likely suspects.

OpenAPI

OpenAPI might be the most widely adopted and best known (even if people still think it is called “Swagger” – it isn’t) API description formats around. It’s an open format; different people from different organisations contribute to and maintain the standard, and all the changes are made through public GitHub activity and open meetings. Disclaimer: I’m one of the maintainers of the OpenAPI specification.

OpenAPI descriptions are written in JSON or YAML format, and they seek to describe the endpoints, requests and responses of an API. This format aims to compromise between API producers, and the consumers of those APIs. In particular it includes user-facing information such as rich text description fields, and supports the inclusion of examples as well. Some organisations generate OpenAPI from their source code, in which case the text content and examples are usually fairly minimal.

OpenAPI is brilliant for RESTful(ish) APIs, and may be useful for other HTTP formats.

AsyncAPI

AsyncAPI is very much from the same school of thought as OpenAPI, but it mostly describes event-driven APIs rather than HTTP ones. Event-driven APIs can use many, many differently protocols such as Apache Kafka, MQTT, websockets, AMQP/RabbitMQ, SQS and many more things including some I hadn’t heard of before!

AsyncAPI is therefore more complex than OpenAPI, and any applications that use it tend to have more AsyncAPI specifications in the mix since each producer, broker, and consumer may publish its own API description to describe how to interact with it. AsyncAPI is mostly used by machines and enables us to smoothly transfer many many messages around smoothly and without losing our minds.

AsyncAPI is great for any event-driven applications that use protocols other than HTTP.

gRPC Service Definition

RPC stands for “Remote Procedure Call” and gRPC is a standard service definition format. It’s very code-driven, with established ways to declare the service itself and the data payloads that can be used with the various functions. The open standard means that it can be used in multiple technology stacks, and gives us a good option for using open standards with RPC-style APIs.

gRPC is pretty lightweight and it is commonly found in microservices in organisations where REST didn’t catch on.

SOAP and WSDL

I always refer to WSDL as the original API description language, it and SOAP have been around for a long time and pre-date most of the other entries in this list. SOAP definitely isn’t the new shiny thing, but it’s still in active use in many organisations and it has earned its place.

Generally seen as a fairly bulky API format, SOAP services are usually XML-based RPC services. Use of XML gives great support for strict and structured data (in contrast to JSON as used in some modern API formats) and this is one reason for SOAP’s staying power. Inertia also counts for a lot, especially in the more established enterprises where these tech stacks are most likely to be spotted.

GraphQL

GraphQL was the new hotness a few years ago but it’s not a replacement for all APIs; merely a great solution for some specific use cases. GraphQL is a web-enabled data fetching interface where the client/user defines the fields that should be returned, and can also add related data to make for unexpected and complex queries. For offering a flexible reporting interface, GraphQL is a tool of beauty and satisfaction for both producer and consumer. For replacing a CRUD (create/read/update/delete) API, GraphQL is ….. not that.

The hype is fading, but GraphQL is not. The tools are maturing and awareness and understanding are improving.

Standards matter

Open standards enable us to build applications that talk to one another and achieve more than we could do alone. Choosing and adopting standards in your own work does matter, and being aware of what is out there is very important for tech professionals of all stripes. Hopefully this rather short and irreverent roundup gave you something new or useful (or both!).