---
title: API Design
description: API design is the process of planning and architectural modeling of application programming interfaces. You will understand how to create secure, scalable, and intuitive RESTful or GraphQL endpoints that facilitate seamless communication between software systems.
category: programming-tech
subcategory: software-architecture
difficulty: beginner, intermediate, advanced
url: /subject/api-design
---

# API Design

API design is the process of planning and architectural modeling of application programming interfaces. You will understand how to create secure, scalable, and intuitive RESTful or GraphQL endpoints that facilitate seamless communication between software systems.

## Available Resources

2 Books • 4 Websites

## Websites

### 1. OpenAPI Specification

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.

**Difficulty:** Beginner | **Price:** Free

**Link:** https://spec.openapis.org/

**Tags:** openapi, api-specification, rest-api, api-documentation, json-schema

### 2. 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.

**Difficulty:** Beginner | **Price:** Free

**Link:** https://apisyouwonthate.com/

**Tags:** api-design, rest-api, openapi, api-versioning, http

### 3. 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.

**Difficulty:** Advanced | **Language:** English | **Price:** Free

**Link:** https://google.aip.dev/

**Tags:** api-design, resource-oriented-design, api-standards, pagination, api-versioning

### 4. 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.

**Difficulty:** Intermediate | **Language:** English | **Price:** Free

**Link:** https://opensource.zalando.com/restful-api-guidelines/

**Tags:** rest-api, api-guidelines, api-versioning, pagination, openapi

## Books

### 1. The Design of Web APIs, Second Edition

**Author:** Arnaud Lauret

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.

**Difficulty:** Beginner | **Language:** English | **Price:** Paid

**Link:** https://www.amazon.com/dp/1633438147?tag=edmonddante07-20

**Tags:** api-design, rest-api, openapi, api-versioning, api-governance

### 2. APIs: A Strategy Guide

**Author:** Daniel Jacobson, Greg Brail, Dan Woods

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.

**Difficulty:** Intermediate | **Language:** English | **Price:** Paid

**Link:** https://www.amazon.com/dp/1449308929?tag=edmonddante07-20

**Tags:** books, technology-computer-science, software-architecture

---

*This content is part of Dantes.io - Your Treasure Map to Knowledge*

*Curated by humans at Dantes.io. Personal study use welcome; republishing this curation requires permission (team@dantes.io).*

View this page online: https://dantes.io/subject/api-design