Mastering API Architecture: API Fundamentals

Byron McNaughtSr. Solutions Marketing Manager

Application Programming Interfaces, or APIs, are all the rage.

While APIs are not new, recent phenomena such as accelerated digital transformation during COVID-19, enhanced software integrations, and efforts to replatform legacy apps for the cloud, has resulted in continuous API sprawl—impacting management, security, and even architectural choices organizations make in order to succeed in the modern digital economy.

APIs, in essence, can represent the rise of the machines. Except, fortunately, humans still have control over their construction, management, and security (at least for now).

Fundamentally, in “API speak” (so to speak), the consumer generally sends queries or requests to the producer, through unified interfaces consisting of various standards, schemas, and specifications.

For example, the National Weather Service (the producer) contains daily weather data. The weather app on your phone (the consumer) calls, or more specifically, queries, this system via the WeatherKit REST API, and then renders the data through the weather app user interface. While this is a simple example of a popular app used by millions of users, it is noteworthy that machine-to-machine communication represents the lion’s share of traffic for modern digital experiences, and it’s powered by APIs.

There are a number of technology benefits that translate to business value afforded by APIs:

When it comes to the implementation of APIs, there are a number of considerations. Specifically, with respect to modeling, versioning, and contract testing, which help to decouple dependencies and ensure interoperability during design, construction, and maintenance.

There is no right or wrong way to build, manage, and secure an API. In fact, when APIs started to proliferate, it became necessary to standardize on the shape and structure of APIs in order to consume them at scale. Enter the OpenAPI Initiative and resulting OpenAPI Specification (OAS). Swagger was the original reference implementation of the OpenAPI Specification, and most tooling has now converged on using OpenAPI, which still maintains its swagger (HA!)

In fact, an API can be constructed using a variety of standards, schemas, and specifications. For example, a RESTful presentation, a gRPC service, and connections into a GraphQL schema.

Implementation	Overview	Benefits	When to Use
	REpresentation State Transfer (REST) provides a lightweight architectural model to describe unified interfaces, most commonly applied using HTTP as the underlying transport protocol. REST is by far the most widely deployed implementation of API-based architectures. Postman 2022 State of the API Report	REST has some very basic rules, with low barrier to entry and a strong domain model, making it relatively straight forward to implement. As a layered system, the complexity of systems behind the REST interface is abstracted. For example, the consumer is not aware that they are interacting with a database system behind a web service. REST has flexible support for content types (including JSON and YAML).	When the OpenAPI specification is sufficient for sharing the shape and structure of APIs with consumers. When caching needs to be determined dynamically based on HTTP headers, since requests from producer to consumer are stateless by default. When extending a resource model for a single API provided by the producer or offering multiple APIs on the same base URL using API Gateways.
	GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling those queries with existing data (developed by Facebook and now part of the Linux Foundation).	Provides a query language to query across multiple sources.  Allows clients to ask for exactly the fields required, including fields that span across multiple APIs, reducing first-time-to-load. Schema language specifies the types in individual APIs and how APIs combine, providing the ability to provide a single version across all APIs—simplifying version management.	As a complementary technology placed over existing legacy systems to abstract complexity.  When an API consumer requires uniform access, filtering, and querying over a wide range of interconnected services. With mobile devices, which are constrained by smaller screens and network availability.
	gRPC is a modern, open-source, high performance Remote Procedure Call (RPC) framework under stewardship of the Linux Foundation.	Highly performant and reliable through use of HTTP/2, lightweight protocol buffers, serialized payloads, and stateful implementations. Pluggable support for load balancing, tracing, health checking, and authentication. High interface function and message interoperability with rich tooling support for all languages.	For the last mile of distributed computing to connect devices, mobile apps, and browsers to backend microservices and for cross-platform apps with mobile to desktop/IoT interaction. For inter-container traffic ("East-West"). With external interfaces ("North-South") that require streaming, and for streaming apps such as chat, financial, news.

With that primer on API fundamentals, we’ll explore how to build, manage, and secure API architecture in subsequent posts before putting it all together by replatforming a legacy app for the cloud.

Want to get ahead? Download the eBook today:

Mastering API Architecture | O'Reilly eBook

About the Author

Byron McNaughtSr. Solutions Marketing Manager

More blogs by Byron McNaught