Mastering API Design: Standards, Practices, and Real‑World Guidelines

What Is an API Specification

API is the interface definition between modules or subsystems. Good system architecture relies on well‑designed APIs; a poorly designed API makes future development and maintenance difficult. Defining clear API specifications improves internal service interoperability, provides a consistent external experience, and facilitates integration.

Common specifications include OpenAPI Specification and the Google API Design Guide . OpenAPI gives detailed rules for RESTful APIs and has become the de‑facto standard, while Google’s guide offers best‑practice recommendations that apply to RESTful and other API styles.

Although RESTful design is widely publicized, not all cloud providers follow it strictly. For example, AWS and Alibaba Cloud favor RPC‑style APIs, whereas Google and Azure predominantly use RESTful APIs.

RESTful APIs benefit from HTTP’s ease of use, making heterogeneous systems easier to integrate, while RPC APIs offer broader framework support and lower‑level flexibility at the cost of higher complexity.

Choose the style that best reflects business characteristics and simplifies client operations.

Ensure the team has the capability to design resource‑oriented APIs if a RESTful approach is selected.

Verify that tooling and automation support the chosen style and offers a good cost‑benefit ratio.

Consider industry trends and interoperability with other systems.

When users access a service via an API, they are performing actions on resources. A unified resource model provides clear structure, aids understanding, aligns API with backend entities, streamlines collaboration, simplifies platform implementation, and makes ecosystem integration more efficient.

Clear API structure helps users understand the service.

Aligning API with backend entities enables more complete services.

Consistent resource operations improve product collaboration.

Uniform resource models simplify underlying platform implementation.

Standardized resources make ecosystem integration easier.

After deciding on a design pattern and resource model, pay attention to naming, parameter naming, attribute naming, data formats, and error codes. Additional considerations include:

Adopt a naming convention that keeps API style consistent and reduces comprehension cost.

Use common standard verbs (e.g., read/query/describe/list/get) for similar operations.

Standardize frequently used parameters (e.g., pagination).

Define uniform conventions for idempotent, pagination, and asynchronous APIs.

Design clear error codes and distinguish between public and business‑specific codes.

OpenAPI Specification

This specification follows RESTful architectural guidelines and references public resources such as GitHub, Azure, Google API Design Guide, Tencent Cloud, and Alibaba Cloud.

1. Protocol

All API communication must use HTTPS to enhance security, especially for public APIs.

2. Versioning

Three common versioning approaches:

Include the version in the URL, e.g., http://api.example.com/v1.

Pass the version as a query parameter, e.g., http://api.example.com?version=1.0.

Specify the version in an HTTP header, e.g., Accept: application/json; version=1.0. This is recommended for new services.

3. URI Schema

URI format:

URI = scheme "://" authority "/" path ["?" query] ["#" fragment]

. URLs are a subset of URIs; each resource should have a unique URL.

Use hyphens instead of underscores, keep URLs lowercase, and avoid file extensions. JSON is the preferred response format; other formats should be negotiated via the Accept header.

4. Resource‑Centric URL Design

Resources are the core of RESTful APIs. URLs should be noun‑based, hierarchical, and avoid verbs. Example GitHub repository URLs:

/users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branches/:branch

Common mistakes include placing verbs in URLs (e.g., /users/show/1); the verb belongs in the HTTP method.

5. Correct Use of HTTP Methods

Typical methods:

GET – retrieve resources.

POST – create a new resource.

PUT – replace an existing resource.

PATCH – modify part of a resource.

DELETE – remove a resource.

Less common methods include HEAD, OPTIONS, and (rarely used) TRACE and CONNECT.

Methods can also have the property of "idempotence": the effect of N > 0 identical requests is the same as a single request.

6. Status Codes

HTTP responses use three‑digit status codes:

2xx – success.

3xx – redirection.

4xx – client error.

5xx – server error.

Common codes include 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests, etc.

7. Error Handling

When an error occurs, return a clear message field in the response body, e.g.:

{
  "message": "Error details"
}

Guidelines: assume the user may not be an API expert, avoid exposing internal implementation details, keep messages concise, and provide links for further information if needed.

8. Naming Rules

Names should be simple, intuitive, and consistent across APIs, resources, collections, methods, and messages. Use American English spelling, common abbreviations, and avoid overloaded or ambiguous terms.

9. Authentication & Authorization

Authentication verifies identity (e.g., password, token). Authorization ensures the user has permission for the requested operation. Unauthorized requests return 401, forbidden requests return 403 (or sometimes 404 to hide private resources).

10. Rate Limiting

To prevent abuse and DDoS attacks, limit request rates and communicate limits via headers: X-RateLimit-Limit – maximum requests per hour. X-RateLimit-Remaining – remaining requests in the current window. X-RateLimit-Reset – time when the limit resets.

Example response headers:

X-RateLimit-Limit: 18000
X-RateLimit-Remaining: 17995
X-RateLimit-Reset: 1590570990

11. Writing Good Documentation

Provide clear explanations for each request and response parameter, include complete examples, and highlight important considerations so developers can use the API without needing additional support.

References

OpenAPI Specification – https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md

Google API Design Guide – https://cloud.google.com/apis/design

GitHub API Design – https://developer.github.com/v3/#current-version

Versioning REST Services – https://www.informit.com/articles/article.aspx?p=1566460

HTTP Status Codes – https://httpstatuses.com/

RFC7231 – https://tools.ietf.org/html/rfc7231#section-6