Writing API Design Standards
An 8-step guide to tailoring API design standards to your organizational context
The Role of API Standards
API Development Standards are a focused collection of imperatives, conventions and guidance, and are intended to improve the consistency, stability, generality and usability of business resource APIs. They may be self-contained or reference external standards. They may offer best-practice recommendations and provide a basis for quality assessment.
Balancing the benefits to development teams of an enterprise landscape of rich, composable, self-service business data against the impost on implementation flexibility is a difficult line to tread – standards, just like models, must learn from implementation and improve through engagement and iteration.
Fit-for Purpose, Tailored to the Enterprise Context
This discussion will touch of a number of conventions and standards that will be relevant in a large enterprise environment. While sample guidance and exemplars are offered in this cluster of articles, there is often more than one tried-and-tested approach in any one area of API design — specific tactics and conventions should be tailored to the target environment.
MUST, SHOULD, MAY Keywords
In the context of the following sections and linked documents, the words ‘must’, ‘should’ and ‘may’ serve as a loose indication of the importance of a concept. Were these concepts to be translated into enterprise guidance, occurrences of these words SHOULD be considered against their definition per RFC 2119 and aligned and capitalized as considered appropriate.
1. Principles, Concepts and Terms
Introduce the motivation behind and importance of API development standards to your organization. It is important to introduce the maintainers of the standards and provide a means for stakeholders to engage and provide feedback.
Briefly outline and/or define important concepts and terms, especially if definitions are loose in common usage. Here are a few candidates:
REST
The REST architectural style “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). The tooling and patterns for REST APIs are relatively advanced, and REST API technology literacy is relatively high.
REST Model
A REST model will describe a business resource, and how client systems interact with it. The model will detail operations, methods and paths. It may include assertions and status codes. It is aligned with the domain data model, though abstracted to enhance composability, generality and stability. From the REST model and the constraints provided by enterprise API standards, it is possible to generate a prototype API specification.
Types of API
There are a number of ways to slice and dice APIs into categories, however in the enterprise context, the two most important perspectives in respect to governance is who owns the data, and who wants it — that is to say, the ‘canonical’ source of the data (source-of-truth) and the developer community.
— Source-of-Truth
Business Resource APIs are the source-of-truth for business data and are the product of a process of Domain Driven Design. Business resources are the nouns of a system, such as ‘applications’ and ‘applicants’. Resource APIs provide a context for interaction with a business capability, represent the business facts about a business domain. Business resource APIs are always secured by an enterprise API gateway, and ideally, secured by OAuth/OIDC and API scope authorization. These APIs must be stable, reusable, discoverable and subscribe-able via an enterprise API developer portal.
Mediating APIs, including experience APIs, will tend to be tailored to specific applications (SPA/PWA/Mobile) or use-case requirements. These APIS are not the source of truth for business information — data requirements are composed, cached or replicated from enterprise resource APIs. There may be limited potential for re-use or need for discoverability. Services exposing experience APIs will typically manage their OWN cloud-native API gateway, in conformance with governing patterns created specifically for this purpose. Discretion is required when translating conventions to a mediating/experience API context.
— Developer Community
Internal APIs serve internally controlled client applications, while external APIs serve the third-party client applications external to the organisation. Clients belonging to partner organizations may constitute a third community of application developers. APIs published for consumption by these communities will be hosted on separate gateways and discovered via separate portals.
Internal API Catalog: The Internal API catalog is aimed at developers of internal applications consuming enterprise APIs. Client developer portals and published APIs are available from enterprise-controlled networks.
External API Catalog: The External API catalog is exposed to public (‘citizen’) and external institutional developers and applications. APIs modelled for external consumers are purposefully abstracted to prevent over-exposure of data and models.
Partner API Catalog(s): A third ‘trusted partner’ category may encompass more than one catalog — a trusted partner community may be defined by a community of OIDC/SAML federated trust, and/or a trusted network.
API First, API-as-a-Product, API Management, API Governance
More on API strategy and architecture concepts…
2. API Lifecycle Management
A shared API lifecycle model and vocabulary will simplify governance and enhance productivity. An API Lifecycle model should be tailored to a particular organization context and widely socialized.
API Lifecycle Phases
The API lifecycle is sometimes characterized in terms of production readiness, sometimes in terms of development stages. In an enterprise managed API context, an API lifecycle must encompass both of these perspectives, as well as the reality of multiple environments and pre-production consumer feedback and iteration.
API Lifecycle phases and lifecycle states are described in the article API Lifecycle Management
Managing API Versions
Semantic versioning would ideally be managed across all derivative artifacts by domain modelling tooling. The following rules apply:
{MAJOR}.{MINOR}.{PATCH}
- MAJOR version when incompatible or breaking API changes are made,
- MINOR version when functionality is added in a backwards-compatible manner, and
- PATCH version when backwards-compatible bug fixes are made.
Versioned URLs are widely employed for the management of API versions. The scheme is somewhat limiting but uncomplicated, making it easy for clients to comprehend and control which API versions they interact with.
Versioned URLs must only include the MAJOR version as part of the URI, in the format ‘v{MAJOR}’, e.g.
/membership/v1/applicantsManage the impact of major (breaking) version changes:
- Justify, document and socialize proposed changes.
- Decouple cut-over — maintain a deprecated version.
- Communicate a retirement schedule to API subscribers.
Versioning options and considerations are covered in the article Versioning Managed APIs.
Registering API Resources with IAM
It is essential to provide clear and efficient guidance for the registration of new business resources and access policies to API Management, Security Token Service (STS) and Identity Access Management (IAM) platforms.
Registration of API resources is further discussed here: Securing APIs with an Integrated Security Framework
API Design and Documentation
API Design Practice: Robust, coherent and composable resource APIs need to be anchored in a validated model of the domain. Contemporary agile-aligned processes and domain modelling tooling give a lean focus and form to Domain Driven Design, and facilitate sharing and collaboration on the model.
If your organization has adopted enterprise API design practices, tools or platforms (recommended), an introduction would be warranted, together with links to ‘getting started’ resources.
More on API Design Practice:
API Design Patterns: Business resource APIs provide a context for interaction with a business capability and the business facts about a domain, and when consistently modeled, discoverable and subscribable, they become the backbone of a federated data platform. Guidance to improve the usability of APIs is vital. If the enterprise maintains patterns and templates for experience APIs, these should also be referenced.
More on this topic: Design Patterns for Business Resource APIs
API Documentation: The OpenAPI Specification (OAS) defines a standard, programming language agnostic interface description for REST APIs. Importantly, the specification is widely supported by API Management platforms, and by a number or domain modelling platforms.
Adoption of the most current, generally supported specification version is recommended. Take the time to research the level of support offered by commercial API management platforms — including both gateway and developer portal support for key features.
OpenAPI document linting rules should be clearly defined. Spectral OpenAPI rules are widely referenced as a base OpenAPI document ruleset.
Documentation rules are discussed here: API Documentation Rules
Integrated DevOps
A well-defined process of model driven development, complimentary tooling and vertically integrated DevOps can substantially reduce friction between domain model development and delivery.
Source Control and Continuous Integration: API specification documents and config files should be co-located in a common repository with the service implementation. API Gateway CI-CD pipelines are triggered from the product pipeline.
CI-CD Pipeline Enrolment: CI-CD requires that APIs are published by DevOps automation to the relevant API & event management platforms simultaneously with the deployment of the business service.
Enterprise endorsed DevOps tools, platforms and frameworks should be identified in API Lifecycle Management guidance, together with links out to more detailed tool and platform-specific documentation and ‘getting started’ resources for CI-CD enrolment.
Typically, onboarding into lower (dev or sandpit) environments will present a low barrier, however an autonomous CI-CD pipeline will require tighter governance and accountability.
Managing API lifecycles with model driven development, API generation and automation is discussed in Managing API Lifecycles with Model Driven, Integrated DevOps
Testing Practices and Platforms: Enterprise testing requirements, tools and platform guidance should be provided, together with links out to more detailed tool and platform-specific documentation and ‘getting started’ resources.
API testing concepts are discussed here: API Bites — API Testing
3. Path and Naming Conventions
Consistency is Usability
Consistent naming conventions enhance the coherence, predictability and usability of APIs. There are a number of factors that may influence naming conventions. This might include dominant development languages and frameworks, and conventions already employed in legacy messaging protocols, data dictionaries etc. It is a good idea to seek buy-in from stakeholders, particularly developers.
Field Names
For request and response body field names (and query parameter names), case MUST be consistent. Either lowerCamelCase or snake_case schemes will ordinarily be mandated within an organization, with lowerCamelCase arguably the more popular scheme, e.g. "familyName" : "Jones"
Fields that represent arrays should be plural nouns (e.g. ‘colours’).
Resource Names
Resource names must be plural nouns when referring to a resource collection e.g. ‘/users’. A singleton, such as ‘/users/1234/cart’ must be singular.
https://api.myorg.com/membership/v1/applicationsHyphens are employed to separate words in the URI. In all other situations, the word separation scheme should align with field naming conventions (e.g. camelCase or snake_case).
Resource Identifiers
A resource identifier is unique and immutable, can be a string or numeric value, and must be URL safe. Ideally, resource identifiers will be un-guessable and non-sequential, providing maximum abstraction from Personally Identifiable Information, primary keys, and time or order of creation.
Resource References
Resource identifiers returned with the core data should be referenced consistently — a standard should be mandated.
Popular schemes incude:
- Return an “id” field. e.g.
"id" : "12B34C". The name of the resource is implied, having been addressed in the URL. - Return an unambiguous concatenation of the resource name followed by the “Id” designation, e.g.
"customerId" : "12B34C".
All external resource id references should in any case be concatenation of the resource name followed by the “Id” designation, e.g. "orderId" : "34C56D". Standardizing resource Ids in this format can simplify and improve the clarity of references.
Path conventions
The structure of the URLs by which Business Resource APIs are addressed should be consistent, predictable, and meaningful to clients. Enterprise guidance on URI and path composition can ensure clarity of API context and intent, and therefore usability.
Further reading: Predictable API Path Conventions
Query Parameters
Predictably implemented parameter driven field selection and filtering can reduce over-fetching and enhance composability — without risking a proliferation of client-coupled response document models.
Query parameter names must be consistent with field naming conventions (e.g. camelCase or snake_case).
Filtering is discussed further here: Filtering Conventions
4. Payload Conventions
Encoding
Unicode Transformation Format-8 (UTF-8) is the standard encoding type for all text and textual representations of data through APIs, and is the default encoding for JSON (RFC 7159). UTF-8 encoding must ordinarily be adhered to for APIs published across the enterprise and externally. Other encodings may be used for ‘private’ partner APIs if and only if there are technical limitations to using UTF-8.
Interoperable Data Formats
Enterprise guidance on media type, date-time format and shared enterprise vocabulary (e.g. archetypes such as ‘address’) should be provided to improve the interoperability of APIs. For example:
- All new and uplifted APIs should support the JSON data format at a minimum. This does not preclude other media types, such as XML.
- A consistent date-time format, conforming to RFC3339, should be used.
Request and Response Document Structure
Similarly, a consistent and coherent document structure will enhance the predictability and usability of business resource APIs. There may be applicable regulatory or industry frameworks/formalisms that provide structural constraints, however in general data structures should be as flat and lean as possible — expressing composability and cohesion in alignment with core domain and conceptual contours principles.
Request and response document structure and interoperable data formats is discussed further in Payload Conventions:
Binary and Multi-part Content
Some resources have one or more binary documents associated with them. For example identity verification might require multiple supporting documents. REST interfaces are, however, primarily concerned with data that can be serialized and parsed (and/or validated) by services and platforms that processes HTTP requests. Care needs to be taken with the modeling of binary data to avoid unnecessary imposts on performance and availability.
More on this topic in the article: Binary and Multi-Part Content
HATEOAS, Link Relations and Pagination
In a managed API environment, linking versioned APIs external to the current namespace creates dependencies, and such links may in fact be invalid for some clients when these services undergo major version changes. It is best to reserve links for operations and resources within the same versioned namespace, and align link names with an operationId or to an OAS 3 link name.
More on this topic in the article: The Engine of Application State. Aligning HATEOAS, Affordances and Business Events
5. Request and Response Protocols
Guidance on consistent request and response HTTP protocols should be provided, and should cover (at least):
- HTTPS : Expose only HTTPS TLS-encrypted endpoints
- HTTP Methods : Descriptions and guidance for standard HTTP methods as applied to business resources. Include why (or why not) business services might avoid DELETE, support PATCH for partial updates and support HEAD for enterprise health checks.
- HTTP Request and Response Headers : Describe headers that API resource servers should understand and those that should be applied to API responses.
- HTTP Response Status Codes : Guidance on the HTTP Response codes that may be appropriate for a resource server to return against each of the commonly supported HTTP methods.
- Response Caching : Guidance on cache control, and how HTTP caching can impact APIs.
Request and response protocols are discussed here: Request and Response Protocols
6. Error Handling
Returning a standard HTTP status code for unsuccessful API requests will ordinarily convey adequate, high-level information about the error to the client with little risk of exposing information that may compromise security. Not infrequently however, the intentionally terse HTTP status response (consider ‘400 — Bad request’) impedes timely resolution of an issue.
Reliable and comprehensive enterprise logging, tracing and analytics should be considered the ideal target platform for analysis and resolution of API errors within the enterprise. However, in the absence of consistent, detailed and navigable logs, or in support of data exchange over trusted networks, enterprise error responses might be considered.
When enterprise error responses are introduced into the API framework, business resource APIs may provide additional error information in the response body. Enterprise guidance on error response structure and semantics will be required, as well as caveats around its use.
For example, an “errors” top-level array might be defined, with one or more error objects returned in a collection. Each error object might contain fields that broadly characterize the issue, assist client maintainers in locating or communicating log identifiers and error codes, and potentially provide a reference to problematic data in the request message.
{
"errors": [{
"errorId": "85024bfe-a602-7b3c-82be-301e7d0bd0a6",
"origin": "myDomain.myApp",
"code": "EMM-7b3c82be",
"message": "Data validation error",
"detail": "Future date not allowed",
"source": "profile.birthDate"
}]
}When returning error responses, technical details, technical errors, thread dumps, and process identifiers must be masked. Care should be taken to ensure PII or other classified information is not returned.
7. API Security
Security-by-Design
Data must be classified and regulatory controls identified during the modelling phase in order to ensure robust API security.
Fine-grained data handling and security controls are implemented accordingly by the business service responsible for the data. Corresponding API specification security schemes are derived from matching security controls captured by the domain model against templated enterprise security patterns.
Security-by-design, registration of resources and integrated API security are considered in more detail here
Protecting Resource APIs with API Scopes
API scopes are an extension/overload of the OAuth scope mechanism and are utilized by OAS 3 and many API management platforms to control access to API operations. API scopes determine the scope of client access to a resource API
Primarily, API scopes represent an authorization from the owner of a business resource for a client application to call a particular business resource API. They are sometimes extended to provide first-pass role-based end-user access control.
API gateways will make a low-granularity access decision that asks only “is this a registered client and/or user with a valid API use-case?”. The access token (and the OIDC identity token behind it) is intended to provide the business service with the means to ask the high-granularity access question “Does this particular user have a right to see the requested data?”.
More here on Protecting Resource APIs with API Scopes
Tactics to Secure Sensitive APIs
Guidance on securing sensitive APIs will include:
- API Abstraction : An API must not expose implementation details. Resource identifiers should be non-sequential and un-guessable, providing maximum abstraction from Personally Identifiable Information, primary keys, and time or order of creation.
- Transport Security : Expose only HTTPS TLS-encrypted endpoints. restrict to TLS versions ’n’ or ‘n-1’ (e.g. ‘TLS 1.3 or 1.2’). Locked down resource server APIs with MA from the API Gateway.
- Data Confidentiality, Integrity and Non-Repudiation, : Occasionally, regulatory controls or controls-by-agreement will dictate special handling of data. Careful validation of such requirements and a coherent and consistent enterprise approach can mitigate a potentially considerable maintenance burden
- API Testing : ‘Code-first’ API publishing automation incorporating Policy-as-Code controls and security testing can improve API security. API security testing concepts are discussed here: API Bites — API Testing
- Gateway Security Features : Make use of the Security policy features provided by API Gateway platforms to augment back-end API security and provide defense-in-depth.
API security tactics are discussed in more detail here:
8. Logging, Traceability and Availability
Enterprise Logging, Tracing and Audit
API management platforms provide centralized but narrow views of API health & usage. Every large and growing organization should have an API/integration logging strategy incorporating Security and Incident Event Management (SIEM), and distributed tracing.
Distributed Tracing
A standardised approach to distributed tracing, such as OpenTelemetry, can provide:
- Traceable end-to-end visibility of the service context
- Self-service to detailed incident data, ensuring decreased mean-time-to-resolution and reduced ticket misdirection.
- Insights into trends, data flows and dependencies cross interconnected systems.
- The ability for internal API consumers to troubleshoot without requiring verbose and potentially unsecure error response messages, allowing secure error response policies to be enforced by API gateways.
More on distributed tracing here: Open Telemetry and W3C Trace Context
Audit Logs, Security Incident and Event Management
When a security event occurs, or an authorization decision is made, it must be logged to an enterprise security incident and event management platform (SIEM) where incidents, patterns and trends can be analyzed and acted upon. It is imperative to define the right granularity of logging and to ensure alerts and notifications are appropriately escalated.
Secure Logging Practices
Content (payload) classified as sensitive or otherwise restricted should not be logged by gateways or business services, unless over secure channels and to platforms approved for the retention of data to the appropriate classification. Guidance might include the following directives:
- Ensure logged data is masked and sanitized to prevent exposure of credentials, tokens, Personally Identifiable Information or other sensitive business information.
- Implement an allowed list of characters to mitigate against log injection attacks. Test potential vulnerabilities.
Health Checks
Provide guidance on the API contexts that would require business services to support API health checks, and consider a standardized approach — which might include TCP Open health checks to assess the reachability of a service endpoint (operation path), and/or use of the HTTP HEAD method to provide a more complete measure of API service availability.
Wrap-up
Governed, opiniated standards and patterns will be required to enable seamless interoperability between independent, decoupled domains. While sample guidance and exemplars are offered in this article, there is often more than one tried-and-tested approach in any one area of API design — specific tactics and conventions should be tailored to the target environment.
Involve a broad cross-section of developers, validate assumptions, and aim for practical and unambiguous guidance that will be easily understood by your technical staff. Consider development standards a living document— standards must learn from implementation and improve through engagement and iteration.
