API Design

REST-first, OpenAPI-driven, backward-compatible by default.

REST Principles

Resources as nouns. HTTP methods as verbs:

GET    /users          # List users
GET    /users/123      # Get user
POST   /users          # Create user
PUT    /users/123      # Replace user
PATCH  /users/123      # Update user
DELETE /users/123      # Delete user

# Relationships through URL hierarchy
GET /users/123/orders