API Primer: Core Concepts in API Strategy and Architecture

Published in

API Central

7 min readOct 27, 2023

Aligning on API Concepts

When talking API strategy, architecture and management concepts with IT and business leaders, it is good to have have everyone on the same page. The following is a short primer on several important API concepts that are likely to come up when discussing an API strategy and roadmap. This discussion will briefly cover:

API
REST
API-First, API-as-a-Product
Design-First & OpenAPI
API Gateway
API Management
API Management Framework
API Portal and API Catalog
API Ecosystem
API Governance

First Things First: What is an API?

An Application Program Interface (API) is a set of routines, protocols, and tools allowing software applications to communicate with one another. An application Program Interface (API) allows software to offer services or data for use by another application.

An API specification describes an application programming interface, making it easier for client application developers to build an integration with the service offering the API

‘API’ is a broad term covering a number of integration technologies. The baseline concepts usually associated with the term ‘API’ in connection with enterprise API strategies today are:

Native HTTP methods and protocols
REST (Representational State Transfer) — an HTTP-based, resource-oriented API paradigm
JSON (JavaScript Object Notation) — as the preferred (but not exclusive) data interchange format

However, an API strategy may evolve to embrace complimentary API technologies and architectures.

The REST Architectural Style & Microservices

REST (an acronym for “REpresentational State Transfer”) is a resource-oriented architectural style that;

“provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, generality of interfaces, independent deployment of components” — Fielding, R.T. 2000, Representational State Transfer (REST)

Similarly, microservices architecture is an architectural style that emphasizes independently deployable, loosely coupled services organized around business capabilities and resources.

“Applications built from microservices aim to be as decoupled and as cohesive as possible — they own their own domain logic … These are choreographed using simple RESTish protocols” — Fowler, M and Lewis, J 2014, Microservices.

API-First, API-as-a-Product

API-first is a software design approach that centers on the API as the means of interacting with services and data. It treats APIs as first-class citizens, making APIs more reusable and adaptable, and enabling organizations to move faster and innovate more rapidly.

API-as-a-Product describes a paradigm in which the API is not only the method of delivery — it is the primary product of value being delivered, based on an open business model mindset.

An API product is not an API specification or backend service, but rather a deployable package including code, security/regulatory policies, access model, API documentation, SLAs, and a monetization and/or consumer-engagement model.

Design-First & OpenAPI

Design-first is an approach that prioritizes the design and specification of API-first products, taking advantage of code generators to accelerate development. Design-first is often, but not always, a complimentary facet of an API-first strategy.

Model Driven Development is a design-first approach involving collaborative design workshops and modeling tools to allow a diverse group of stakeholders to collaborate on a composable, evolvable and secure REST model, from which API/Event specifications are generated.

The OpenAPI specification is a broadly supported, de facto standard specification language for HTTP APIs and features a healthy ecosystem of design tools and “one-click” generators for server scaffolding, client code/SDKs, mocking services and API test suites.

API Gateway

An API gateway is a platform or service that sits in front of an API provider and acts as a single point of entry for client applications. The API Gateway routes API calls, enforces SLAs, provides cache management, and protects API back-ends with payload validation, authorization, rate-limiting and other configurable policies.

An API Gateway is often deployed as an access control point and network edge service to control and audit ingress, with close integration with Identity and Access Management and Security Incident and Event Management services.

An API gateway is the source of usage metrics that provide visibility into usage, patterns and trends.

API Management

API Management is about much more than operating one or more API gateways. API Management is facilitated by a platform or framework of services that provide the means to publish, secure, manage and observe APIs, and to discover and access APIs via a self-service API catalog / portal.

An API management platform offers value to API consumers by facilitating self-service discovery and access to APIs — avoiding blocking engagements with platform and provider teams. It provides value to API providers and business stakeholders by facilitating client engagement and SLA management, providing visibility into API usage and trends, and exposing management APIs for decoupled CI/CD deployment automation.

API Portal and API Catalog

An API Portal hosts and authorizes access to the API catalog and API documentation. It facilitates client registration, IAM credential and/or certificate management and API access request workflows.

An API portal will provide a dashboard for API metrics and a manage communication between consumers and providers. Client code or SDKs can usually be generated on and downloaded from an API Portal.

An API Catalog provides the means for application developers to discover, learn about and request access to APIs.

An API Catalog is not dissimilar to a catalog for an online grocery retailer, where potential customers can browse for and arrange access to the products they need.

An online grocery retail business cannot hope to be successful until it can offer a catalog that includes a baseline collection of core, broadly relevant products. In the same way, a vibrant API ecosystem requires a rich API catalog of reusable, coherent and composable APIs, covering a critical mass of core business capabilities. To this end, API quality governance is essential.

API Management Framework

A COTS API Management platform alone is not a complete solution.

Decoupled, well governed self-service integration is enabled via API management platforms inter-operating with a framework of centrally managed enterprise services.

Full stack API management framework components encompass all aspects of API security, client and provider onboarding, lifecycle and release management, client engagement, support, monitoring and observability.

API Ecosystem

An API Ecosystem encompasses the network of API consumer and API producer communities, as well as the APIs offered in a community facing API catalog.

An organisation may manage multiple API ecosystems encompassing Internal, partner and public API communities.

Community and Catalog management are at the heart of an API ecosystem. Communities must be actively engaged, and a catalog of high quality, composable APIs must be iteratively built up.

API Governance

API Governance is a topic that spans the governance organisation, API strategy, API standards and patterns, API lifecycle management, governance tactics and ecosystem management.

API Lifecycle Governance will be focused on facilitating secure, standards compliant API lifecycle management by decoupled and autonomous business domains. API Lifecycle management covers Design, Build & Release and Runtime governance phases

Minimum-viable-governance is a term sometimes used to describe governance that is guided and enforced by collaborative tooling, automation and policy-as-code to ensure minimal blocking touchpoints.

Wrap-up

This has been a lightning tour of some key concepts in API strategy, architecture and management. There is a lot more to be said on each of these topics, and some considerable variation in how these terms are defined. If these concepts are important to your API strategy, it is a good idea to settle on and document an agreed definition.

If you are interested in reading further, here are some additional resources on API strategy, architecture and management: