api-and-interface-design

API and Interface Design - A Guide to Stable Interface Design

Skill Overview

API and Interface Design provides a comprehensive guide to designing stable, misuse-resistant interfaces. It helps developers and architects design a wide range of public interfaces, from REST APIs and GraphQL interfaces to module boundaries and component properties, making correct usage easy and incorrect usage difficult.

Applicable Scenarios

1. Designing API Endpoints

When you need to create a REST or GraphQL API, this skill provides contract-first design methods, consistent error-handling semantics, and pagination and filtering conventions to ensure that APIs are stable and easy to document. It is suitable for microservice architectures, open platforms, and projects with separate frontends and backends.

2. Defining Module Boundaries and Team Contracts

When dividing microservice boundaries, establishing interfaces between teams, or designing dependencies between internal modules, use the single-version rule to avoid dependency conflicts. Typed interface contracts help ensure stable cross-team collaboration and prevent behavioral coupling caused by Hyrum’s Law.

3. Modifying Existing Public Interfaces

When extending an API without breaking existing consumers, this skill provides guidance on maintaining backward compatibility by adding optional fields rather than removing or modifying existing ones, while planning a reasonable deprecation and migration strategy.

Core Features

1. Contract-First Design Principles

Define the interface contract before implementation, including input and output types, error response formats, pagination structures, and validation rules. This applies to REST endpoints, GraphQL schemas, TypeScript interfaces, and database schema design, ensuring that types serve as documentation.

2. Consistent Error-Handling Semantics

Use a standardized error response format—HTTP status code plus a structured error body—covering 400 client errors, 401 unauthenticated requests, 403 forbidden requests, 404 not found, 409 conflicts, 422 validation failures, and 500 server errors. This avoids confusing consumers with different error formats.

3. Boundary Validation Strategy

Validate external input at system boundaries, such as API routes, form submissions, external service responses, and environment variables. Internal code can trust data that has already been validated under the type contract. In particular, responses from third-party APIs must always be treated as untrusted data, preventing validation from being scattered throughout internal code.

Frequently Asked Questions

What Is Hyrum’s Law, and How Does It Affect API Design?

Hyrum’s Law states that with a sufficient number of users of an API, all observable behaviors of the system will be depended on by some users, regardless of what the contract promises. This means that even undocumented behaviors—such as error message text, response timing, and field ordering—become de facto contracts once users depend on them. Therefore, designs should deliberately control exposed observable behavior, avoid leaking implementation details, and plan deprecation strategies from the outset.

Why Should API Design Be Contract-First?

A contract-first approach makes the interface definition a specification that can be reviewed and discussed, while implementation simply fulfills the contract. Its benefits include: types serve as documentation, allowing consumers to make type-safe calls; design issues can be discovered before implementation, avoiding refactoring; contract impact can be assessed before changes are made, preventing existing users from being broken; and parallel development is supported, with consumers mocking against the contract and providers implementing against it.

What Are the Differences Between REST API and GraphQL Interface Design?

REST APIs use resources and HTTP methods such as GET, POST, PATCH, and DELETE, making them suitable for standardized CRUD operations. They naturally support HTTP caching and layered proxies, and endpoint names use plural nouns rather than verbs. GraphQL uses a single endpoint with a defined schema, making it suitable for complex queries and reducing the number of requests. Clients can retrieve exactly the fields they need, but Query, Mutation, and Subscription structures and a type system must be designed. Both should follow the principles of contract-first design, consistent error handling, and boundary validation.