General Guidelines at Reference Model for API Methodology

At AXPE’s API Expertise Cluster, we have defined an API Strategy aimed at establishing a set of Best Practices for API design.

As part of our article series “AXPE Reference Model for API Methodology,” we will detail each aspect of this methodology. The first article will cover Introduction and General Guidelines, followed by topics such as Design, API Error Management, and Data Modeling.

Objectives

The primary goal of this methodology is to standardize and homogenize API structures to:

  • Simplify API consumption for both internal teams and external providers.
  • Facilitate decision-making in API design.
  • Accelerate development projects by ensuring a common language across teams.
What is an API?

An API (Application Programming Interface) is an interface exposed by a system to establish a technical and functional means of interaction with multiple systems. It acts as a contract and access gateway that enables system interoperability, with the following key characteristics:

  • APIs must be properly visualized and exposed through an API Portal.
  • They must be versioned correctly.
  • API consumption must be managed through application permissions, consumption plans, and visibility settings.
  • APIs must follow a recognized standard (e.g., OpenAPI 3, RAML, etc.).
  • Design and implementation must be decoupled.
  • API design and implementation must be in English.
  • API documentation may also be in English.
  • Every API must have a mock version, a static response model that simulates real API behavior.

General Guidelines

1. Target Audience

This methodology is designed for technical and functional teams with experience in API specification, particularly those using API Management tools such as Kong, Mulesoft Platform, or Azure API Management.

2. Specification Structure

An OpenAPI document can be structured as a single file or divided into multiple interconnected parts using keywords like .Schema, Object, $ref, etc.

We recommend naming the specification file openapi.yaml.

At AXPE, we follow the “divide and conquer” philosophy, favoring small, modular, and highly specific structures that can be reused within a single OpenAPI document or across multiple documents.

3. API Specification

API specifications define practices, communication protocols, and structures that establish the contract.

  • Synchronous APIs must follow the OpenAPI specification.
  • Asynchronous APIs must use both OpenAPI and AsyncAPI.
  • The OpenAPI version must be consistent across all APIs (always version 3).
4. Language

English is the mandatory language for defining API specifications.
This applies to URLs, objects, attributes, and documentation (descriptions, examples, etc.).
The reason is that English is the predominant language in the global IT community.

5. Examples

Examples should be defined at the request and response level for each operation.

They serve multiple purposes:

  • Enhance understanding of API design for both API developers and API consumers.
  • Enable the creation of API mock tests, allowing consumers to perform unit testing independently of backend development progress.

While not mandatory (must), we strongly recommend (should) providing clear and well-documented examples as part of the API design standard.

6. Attribute Extension

When custom attributes need to be defined, they must follow the format “X-“ (e.g., X-Request-ID).

Attribute naming must be aligned with the business entity data dictionary. A well-structured API must reference a catalog of business entities and their attributes to ensure alignment with business processes, products, and services.

APIs may also contain technical or control attributes that are not part of business entities. These should be clearly identified to differentiate them from business-related information.

7. Object Structure

Each defined object must include a title attribute, with the value matching the object name.

This allows validation tools (e.g., Spectral) to recognize and enforce predefined rules.

8. Versioning

API versioning is critical as business needs evolve.

We follow Semantic Versioning (semver.org) to manage API evolution.

  • API designers are responsible for defining and maintaining versions.
  • The governance team ensures proper version control across APIs.

Semantic versioning provides comprehensive coverage for tracking API evolution and ensuring compatibility.

Conclusion

At AXPE’s API Expertise Cluster, we consider these general guidelines essential for establishing the fundamental principles of our Reference Model for API Methodology.

In our next article, we will cover API design standards and best practices, including:

  • HTTP status codes per verb.
  • Using POST for actions (event handlers/controllers).
  • Header configurations.
  • URL structuring and resource modeling.
  • HATEOAS, pagination, and filters.

This version maintains the clarity and technical precision required while making it structured and easy to read. Let me know if you need adjustments for tone or emphasis!