API Architecture Track Recap From QCon Plus

The API Architecture track at QCon Plus took place on November 9 and featured six speakers and panelists discussing topics relevant to software engineers and architects who design, build, and maintain APIs. These ranged from broad concepts such as extensibility and API lifecycles, to a showdown between REST, GraphQL, and gRPC to determine the best technology to use when building an API.

Christi Schneider, a software engineer at Square, presented “Building with Extensibility,” which gave a deep dive into what it means to have an extensible system, and specific challenges it creates. Schneider made a good case for why extensibility needs to be considered early in the design process and requires more thought than simply hoping to check a “public API” box on your list of features. Product planning needs to consider extensibility as a foundational capability and doing so allow the software to be easily expanded upon, whether by other internal teams or external partners and 3rd-parties.

However, she cautioned that none of this comes for free, and a truly extensible system brings with it additional concerns. For example, the developer support should include public documentation, training, and forums, and customer support needs the ability to determine if an issue is part of the core system or a 3rd-party’s. If implemented correctly, an extensible system provides increased developer satisfaction as well as new opportunities for product growth.

An API’s lifecycle is a subset of a software system’s development lifecycle, and has similar, but more focused needs for design, development, and maintenance. According to Kin Lane, chief evangelist at Postman, using API standards and specifications improves communication, which makes managing the API lifecycle easier. OpenAPI (formerly Swagger) is the de facto standard for describing http-based APIs. AsyncAPI is based on OpenAPI and adds syntax relevant for event-driven APIs. Both use JSON Schema to describe the message contracts that flow into and out of an API. 

The most common use case for API specifications is documentation, but Lane says the latest innovations go much further. Because the specifications are both human- and machine-readable, new tools are constantly being created to improve the API lifecycle. This can start with basic validation tests that an API implements the contract, to auto-generated health, security, and performance tests that can be run during a CI/CD pipeline. Lane believes future enhancements and tooling will result in more automation and repeatability, reducing the effort required to have a well-maintained API lifecycle.

Fran Mendez, founder of the AsyncAPI Initiative gave a coding demo where he used AsyncAPI to build an event-driven app. He used a beta version of AsyncAPI Studio, a browser-based editor, but could also manually edit the YAML for his AsyncAPI specification. The contract defined the publish and subscribe channels, and he created a Mosquitto MQTT server that implemented the specification. The contract was also used to generate a frontend web app that used web sockets to communicate with the server. The final element was sending push notifications to Slack based on a specified event occurring. The demo was a very quick and succinct overview of the current state of AsyncAPI and some of the tooling that currently exists. In the coming years, Mendez expects to see the tooling continue to grow, following what has happened with OpenAPI.

The finale of the track was the API Showdown, an attempt to determine if there really is one technology we should all be using for building APIs. The three panelists each had expertise in a specific technology stack and were asked to present the facts around its capabilities. Matt McLarty, the global leader of API strategy at Mulesoft represented REST. Alex Borysov, a software engineer at Netflix represented gRPC. And Michelle Garrett, a software engineer at Twitter represented GraphQL.

After a discussion that covered origin stories, good implementation scenarios, bad scenarios, and which of the other technologies would make a good partner, the result was “It depends.” Each tech has clear pros and cons, but there is no silver bullet.

REST has the lowest barrier to entry and is commonly used, but it is not optimized for performance or complex querying. GraphQL requires some effort to get setup, including a server and describing your schemas, with the result being a lot of flexibility being provided to your clients. It can greatly reduce the amount of data being transferred, but can also be used incorrectly and result in unnecessary processing. The ideal use case for gRPC is when you need to transfer well-defined data quickly, preferably between two servers. Because the contract, often defined using Protobuf, must be understood on both sides, it can’t easily adapt to dynamic data models.

Even when asked to choose one of the other technologies to pair up with, the panelists gave compelling arguments for both options. As with every architecture decision, there is never a single, right answer for everyone. Deciding what technology to use comes down to analyzing the trade-offs and choosing the option or options that have more positive than negative attributes for your use case.

A full recap of the November 2021 QCon Plus is now available. The next QCon Plus will be held virtually May 10-20, 2022, and the next in-person QCon London will be April 4-6, 2022.


The Outbound Collective — Discover local adventures, hikes, and campsites, and more.

A Digital Timer App Built Using React