OpenAPI Specification
Unknown
Official, versioned text of the vendor-neutral standard for describing HTTP APIs in YAML or JSON, maintained by the OpenAPI Initiative. It defines how paths, operations, parameters, schemas and security schemes are written so tools can generate documentation, clients and tests.
More resources on API Design
APIs you won't hate
Community site founded by Phil Sturgeon with articles, books and a podcast on designing, documenting and evolving HTTP APIs. Topics include REST conventions, OpenAPI, pagination, versioning, error formats and API governance, giving readers practical guidance for building APIs that clients find predictable.
The Design of Web APIs, Second Edition
The best way in for someone new to the topic. A practical guide to designing web APIs around what their consumers need. It covers REST operations and resource identification, OpenAPI and JSON Schema documentation, access control and scopes, versioning without breaking changes, linting and governance, and how the ideas carry over to GraphQL and gRPC.
Google API Improvement Proposals (AIPs)
Google's public set of API design decisions, written as numbered proposals. Start with AIP-121 on resource-oriented design, then read the standard methods, pagination, field masks, long-running operations, errors and versioning. An API linter enforces the rules. This is the most rigorous public treatment of resource modelling, and it is the free primary source behind Geewax's book. Rated advanced because each proposal assumes you already know REST basics.
Zalando RESTful API and Event Guidelines
Zalando's open-source, production-tested rulebook for designing REST APIs. It covers resource naming and URLs, HTTP methods and idempotency, status codes, versioning and deprecation, OAuth2 scopes, cursor pagination, JSON formats and OpenAPI 3.1. It is the best free, practical answer to 'how should a REST API look' on versioning, auth and pagination.
APIs: A Strategy Guide
A 2011 O'Reilly book on APIs as a business decision rather than a coding task. Drawing on Netflix's experience, it covers API business models, legal and security concerns, design choices, metrics and team operations, helping teams decide whether and how to offer an API.