API Design Practice

A practical guide to API QA and the design of stable, coherent and composable business resource APIs

Introduction

An API specification document is a technical artifact, offering little opportunity for meaningful and timely input from business and enterprise stakeholders. It is absolutely the wrong place to begin designing an API. When building an enterprise API catalog of reusable, stable, coherent and composable APIs, an enterprise-guided, domain-oriented API Design Practice is essential.

This guide will cover:

• API Design Goals
• Early and Continuous Stakeholder Engagement
• Iterative, Collaborative Design
• Model Driven, API-First Development
• API Design Tooling

API Design Goals

The API Design Phase is centered around the capture and validation of the domain data model and the state-lifecycle of business resources. The quality of the data / REST model has significant impact on the usability, evolvabilty and security of an API.

Collaborative design workshops and modeling tools will allow a diverse group of stakeholders, from business owners, enterprise and domain architects, data modelers, security architects, REST and EDA SMEs, tech leads and developers, to interact with (and contribute to) the same domain data model, and be notified of changes that interest them.

In this way, the domain model “acts as a Ubiquitous Language to help communication between software developers and domain experts” (Fowler, M 2014, BoundedContext), maximizing collaboration, providing the tightest possible feedback loop, and ensuring that the domain model remains the definitive source-of-truth.

Align Resource APIs with your Business Domain

From the business information, events and processes managed by a System-of-Record business service, are abstracted one or more canonical business resource APIs. Business resources represent the nouns of a system, such as ‘applications’ and ‘applicants’. They provide a context for interaction with a business capability, represent the business facts about a business domain, and when consistently modeled and cataloged, they become the backbone of a federated, self-service data platform.

Design for Composability

Microservices architectures and the REST architectural style enable decoupling, self-service and re-use by moving the responsibility for choreography from the resource server to the client. This shift in responsibility allows business systems to build stable, genericised interfaces to their business resources and capabilities, without tight coupling to client systems, which in turn allows client systems to compose data via self-service integration without a blocking dependency on external teams.

API clients will typically want access to core information about a specific business object, not complex data structures, and they want it FAST. A good REST model is concerned with finding a balance between granularity and cohesive units of business data likely to be of interest to client systems (though not superfluous to their needs). In short, balancing composability with cohesion.

Early and Continuous Stakeholder Engagement

Business domain expertise and enterprise API Design Standards inform The API Design Phase. A REST model provides the means for external systems to securely interact with business objects, data and processes via standard, generic RESTful operations. The quality of the model has significant impact on the usability, evolvabilty and security of an API.

There are many stakeholders invested in shaping and validating the model, stakeholders may include:

• Business owner (domain expert),
• Domain architect,
• Enterprise architects (Security, Data)
• API Platform REST SME,
• Tech lead / API Developers
• Closely aligned client application teams.

Iterative, Collaborative Design

Preparation and Planning

During the planning phase of the project, identify and engage a representative from each of the above-mentioned stakeholder groups. Consider whether there may be closely aligned client application teams or other invested parties that can contribute valuable feedback, and identify a representative from each of these teams.

Identify the tools that you will use for the process and ensure that stakeholders are provided access. Developers/modellers should familiarize themselves with tools, processes and enterprise API design standards prior to commencing the process.

“Bottom up” analysis of legacy systems can be helpful — but ONLY as a means for engineers to bring knowledge of as-is implementation into the room as a contribution to the larger discussion.

Remember that the process is iterative

Capture your understanding of the domain as early as possible — and use collaborative tools and a shareable model to elicit corrections and input from stakeholders.

More on API Standards:

Writing API Design Standards

1. Conduct Design Workshops

Set up an initial workshop with domain SMEs — those with a deep understanding of the business processes, regulatory obligations etc. Collaborative domain-oriented design workshops such as Event Storming are a forum for mutual discovery, validation and agreement on models, boundaries and business events.

When running design workshops (onsite or online) with a number of stakeholders, a collaborative white-boarding tool will allow you to capture, share and validate perspectives on business events, processes, actors and entities. The Event Storming technique can provide some structure to design workshops, and a means to capture collective knowledge about the domain.

A brief overview of the Event Storming process is as follows:

1. Identify a scenario: A short and focused bullet-point description of the process to be captured.
2. Identify events: the things that are happening in your domain (such as “courses selected” or “payment details provided”) — written in past tense and expressed as a flow or sequence.
3. Capture commands and aggregates/entities: as well as actors, external systems, processes/policies and problems/hot-spots as appropriate.
4. Identify bounded contexts: independent clusters of common language and functionality — each bounded context should be ‘decoupled’, expressing its own model, and its own API/s.

The Event Storming process employs coloured ‘sticky notes’ (either physical or digital) to explore, organise and iterate on emerging elements of the scenario. Time-boxing phases of the workshop is an important element of the process. A Miro Event Storming Template will help you get started.

A validated high-level view of business events, commands, aggregates & entities is a key input into the domain data model.

2. Model the Data & Continuously Validate

Capture the aggregates/entities that emerge from design workshops in collaborative data modelling tooling and engage key stakeholders to validate and enrich the model. Consider Enterprise Naming Conventions.

Explore with enterprise data architects and domain architects the applicability of industry models and formalisms, and re-use of ‘enterprise’ entity arch-types such as address data structures etc. A searchable model repository will streamline this activity.

As soon as baseline agreement on the data managed by a system-of-record emerges, seek the advice of security architecture on the classification, caveats and controls applicable to the data. Make annotations in the model against each entity.

Consider REST Modelling Guidance, and validate composability and cohesion with API competency REST SMEs as the model develops. When developing the REST layer, consider Enterprise API Path Conventions and HTTP Request and Response Protocols.

Iterate and circulate significant model changes to the wider group of stakeholders as often as possible — design tooling should assist with stakeholder notification.

More on Modelling Resource APIs:

Design Patterns for Business Resource APIs

3. Generate and Refine your API Specification

When the model is relatively stable, create a versioned snapshot of the model and generate a prototype API specification for technical review and validation. Version aligned API specifications are generated from the REST model, based on standards and policy-conformant rules or templates.

You may choose to work with an initial version “0.x.x” prototype API spec until you are ready to publish. Remember that beyond an initial V1, major version increments must only apply to breaking changes to production (‘live’) APIs.

Validation and Refinement of your API Specification

API definition documents, whether hand-crafted, generated or pre-existing, will need to be reviewed and technically validated, and in many cases further refined.

Use an IDE with OpenAPI/AsyncAPI document linting support — it will provide immediate feedback on API quality and mandatory API document rules.

API document linting rules should be clearly defined. Spectral OpenAPI rules are widely referenced as a base OpenAPI document ruleset.

More on API document linting:

API Documentation Rules

Model Driven, API-First Development

API-first is a micro-or-modular service development model that treats APIs as the primary means of interacting with a business capability and the business facts about a domain. When these API ‘products’ are streamlined for consistency and re-usability, they contribute to a rich and composable federated data platform.

As a primary product of a service, the API is designed first, and used as a template for the service implementation. When building from a validated domain model and API definition document, product teams can take advantage of code generators to accelerate development.

From the API definition document, OpenAPI & AsyncAPI Generators can automatically create a consistent scaffold/skeleton implementation for supported languages (e.g. Java/Spring, Node.js). Mock servers and API Tests can also be generated from the API specification document.

For development to be both API-First and Model Driven, the API specification origin and source-of-truth must be the validated domain model.

Legacy and Proprietary COTS/SaaS APIs

Legacy or COTS/SaaS API definition documents without a sharable data model are more difficult to validate, evolve and map to the enterprise context. However this situation arises when an organization is in transition to new platforms and architectures. Consider:

• Retrospectively capturing the API data model with Model-Driven-Design tooling.
• Which elements of the API and/or OpenAPI document may be iteratively refined/refactored to align with API & document rules.
• Whether a tactical “anti-corruption-layer” integration solution can provide a clean and conformant API

API Design Tooling

Design Workshop Tools

The ‘Event Storming’ technique is white-board centered design workshop amenable to live online collaboration. Judith Birmoser’s Event Storming template for the the Miro digital white-board platform, or an Event Storming template for Mural is an easy way to get started.

Some additional Event Storming resources:

• Event Storming (openpracticelibrary.com)
• Virtual Domain-Driven Design — A community of practise
• EventStorming (eventstorming.com)

Domain Data Modelling & Model Driven Design tooling

Domain modelling tooling should support OpenAPI/AsyncAPI document generation, source control, and management of semantic versioning across the model and its derivative artifacts — features that are helpful in maintaining the currency and traceability of published APIs.

The Jargon Domain Data Modelling Platform

Other platform features strongly supportive of model driven development include design-time model validation, documentation of state-lifecycles, (e.g. state-lifecycle diagrams), mapping and management of dependencies, notification management, and model discoverability, sharing and re-use.

Domain Data Modelling tooling (with widely varying feature-sets) includes:

• Jargon Domain Data Modelling Platform
• Stoplight Studio Enterprise
• Visual Paradigm
• Mendix Low-Code Platform
• Hackolade Studio
• Sparx EA + OpenAPI plugin

API Specification Technical Validation Tooling

Spectral is a widely used open-source OpenAPI/AsyncAPI document linter with an extensible ruleset. The following tools support Spectral linting:

• The Jargon platform supports Spectral linting at the domain data and REST model layers.
• Visual Studio Code : Install the ‘Spectral’ extension by Stoplight. Rule errors and warnings are listed in the Problem console, and is updated dynamically as changes are made.
• Stoplight Studio : Upload an OpenAPI or AsyncAPI specification and spectral will provide immediate dynamic feedback. The warning icon will toggle a side-by-side view.
• CI/CD pipeline : As well as automated Sonarqube analysis of your software source code, integration & build pipelines can support spectral linting of your OpenAPI definition to ensure timely feedback on document quality issues.

Code Generation Tools

There are various locally configurable generators available for different programming languages. Here are some resources:

• OpenAPI Design & Documentation Tools | Swagger
• OAS OpenAPI generators: https://openapi-generator.tech/docs/generators/ and https://github.com/OpenAPITools/openapi-generator
• Various OpenAPI Tools: https://openapi.tools/

Test Generation

The following is a (non-exhaustive) list of testing platforms that support test generation from an OpenAPI and/or AsyncAPI specification document:

Postman API Platform, Thunder Client — Extension for VS Code, karatelabs/karate, Pact (pact.io), Katalon Quality Management, Insomnia API Dev Platform, SOAPUI, REST-Assured + Tcases

Wrap-up

An API specification document is a technical document. It is often generated well into the development effort, and is difficult for less technical stakeholders to parse. Without a guided API design practice, a large enterprise will struggle to govern the quality of business APIs.

In order to maximize opportunities for stakeholder collaboration and provide the tightest possible feedback loop, it important to capture, share and validate REST models well before anything is committed to code. A clearly defined and supported API design practice can ensure that both APIs and their underlying data models are visible, re-usable and governable.

Related Articles on Medium

• Design Patterns for Business Resource APIs
• Writing API Design Standards. An 8-step guide to tailoring resource API design standards to your organisational context
• API Documentation Rules. Improving the quality and consistency of APIs with OpenAPI documentation and linting rules
• API Lifecycle Management. Shaping an API lifecycle model for your organisational context
• Tactics to Secure Sensitive APIs | by TRGoodwill | API Central | Medium
• An iterative approach to Data and API management | by Alastair Parker | Sep, 2022 | Medium