Api-first architecture

As explained in Effective Platform Engineering

API-first architecture designs an API as the primary interface of a capability before building user interfaces or other tools on top of it.

API-first architecture designs the service interface before building user interfaces or developer tools on top of a capability. Every platform capability, integration, feature, and automation should expose an API, whether it is purchased or built. This creates sustainable self-service experiences and clear boundaries between platform teams. section 1.3.3

Apply the pattern by making the interface the stable starting point:

• Define an API for every capability before selecting or building its user interface. section 1.3.3
• Expose purchased capabilities through APIs as well as internally built services. section 1.3.3
• Preserve boundaries and the ability to change as integrations and architectural decisions evolve. section 1.3.3 section 3.5.4

A self-service platform capability

A platform team defines a capability’s API first, then adds a self-service interface or developer tool that consumes it. The same interface supports collaboration across team boundaries and allows the implementation to evolve without replacing every consumer. section 1.3.3

Figure 1.5 Software defined is placed in the middle because it is a core attribute of everything the platform engineer delivers. The rest of the principles share a connection because they continuously evolve, and decisions made in applying these surrounding principles can affect the requirements of the others.

Use the figure to place API-first design within the broader relationship between software-defined delivery, self-service, evolutionary architecture, and measurable platform outcomes. section 1.3.3

How Effective Platform Engineering covers it

How deep it goes

Defines the interface-first rule and explains its flexibility and boundary benefits without prescribing detailed API implementation techniques.

Examples

Uses APIs, user interfaces, developer tools, integrations, and automation as the concrete capability layers.

What it assumes

Assumes a platform-engineering and software-delivery context while establishing service interfaces as a requirement for every capability.

What you can do after

Build self-service platform capabilities by defining APIs before adding user interfaces or developer tools.

How it connects

Connects API-first architecture to self-service, software-defined platforms, evolutionary architecture, loose coupling, and domain events.

liveBookmanning.com

Read Effective Platform Engineering on liveBook Get the book at manning.com

Also explained in

• 

  liveBookmanning.com
  Platform Engineering on KubernetesA software development approach in which an API is designed as the primary interface for accessing a service before client implementations are built.
• 

  liveBookmanning.com
  Secure APIsAPI design first is an approach that defines an API before implementing its producer or consumer.

Compare how 3 books explain api-first architecture →

Related concepts

• FastAPIused by · FastAPI is a Python web framework for building APIs, with type-annotation-based request handling, validation, and automatic OpenAPI documentation.
• contractuses · An API contract is a specification of the operations, data, and behavioral expectations that govern interactions between software components.
• self-serviceproduces · Self-service is a mode in which users independently obtain resources or perform supported tasks without requiring an intermediary for each request.
• design-first approachcontrasts with · A specification-first approach defines and validates an interface or behavioral contract before implementing the system that conforms to it.
• secure by designuses · Secure by design is an engineering approach that incorporates security requirements and protections throughout a system’s design, development, and lifecycle.

This explainer was generated by Manning's knowledge graph from the text of Effective Platform Engineering. The section links point to the parts of the book it draws on.