Documentation

Patterns and conventions I've landed on after years of trial, error, and strong opinions. None of this is new or proprietary. These are well-established practices for building software, and this is how I choose to implement them.

Fundamentals

REST & HTTP Verbs

A quick primer on REST architecture and the HTTP methods that drive it.

Time

Standard formats for datetimes, durations, and recurring schedules.

Identifier Conventions

How to choose and use identifiers: auto-increment, UUID versions, ULID, and when each makes sense.

API Design

API Design Principles

Core principles and conventions that guide the API design.

Naming Conventions

Conventions for naming API routes to ensure consistency and RESTful alignment.

Resource Relationships

Modeling associations between resources: direct endpoints vs. relationship endpoints, association data, and keeping route sets minimal.

Requests & Responses

Error Responses

Standard error response format and HTTP status codes used across the API.

Pagination

Page-based and cursor-based pagination using the Link header.

Expanding Responses

Use the expand parameter to include related resources inline within API responses.

Operations

Rate Limiting

Rate limiting behavior, headers, and best practices for handling 429 responses.

Database

Database Naming Conventions

Consistent naming for tables, columns, keys, and relationships.

Reference

API Reference

Interactive API documentation with live request testing.