# BuildRestAPI (https://buildrestapi.com)

> The definitive, production-grade guide to designing, building, securing, and operating REST APIs for human engineers and autonomous AI agents.

## Core Keywords & Topics
- Build REST API
- REST API Design & Architecture
- REST vs GraphQL vs gRPC vs SSE vs WebSockets
- HTTP Methods & Status Codes (RFC 9110)
- OpenAPI 3.1 & JSON Schema Validation
- Enterprise Internal Microservices with REST
- AI Agent REST Tool Calling & Function Calling
- Idempotency Keys (Stripe Pattern)
- Webhooks & Cryptographic HMAC Verification
- RFC 9457 Problem Details for Error Responses
- High-Performance Cursor Pagination (Seek Method)

## Key Learning Tracks
- Beginner Track: HTTP fundamentals, verbs (GET, POST, PUT, PATCH, DELETE), status codes, URI resource design.
- Intermediate Track: OpenAPI 3.1 contracts, cursor pagination, rate limiting (RFC 6585), JWT vs OAuth 2.1, RFC 9457 error contracts.
- Advanced Track: Idempotency keys, distributed database concurrency, webhook retry queues, enterprise internal microservice architecture.

## Decision Guide: When to Choose REST
- Enterprise Internal Microservices: Over 85% of corporate private services rely on REST due to zero-compilation simplicity, native HTTP caching, and compatibility with AWS ALBs, Envoy, Kong, and standard debugging tools.
- Public SaaS & Developer Platforms: Universal standard; supported natively by all programming languages without requiring custom client SDK runtimes.
- AI Agent Tools: LLMs (OpenAI, Claude, Gemini) consume OpenAPI 3.1 REST schemas natively to perform automated function calling.
- Server-Sent Events (SSE): Choose SSE over WebSockets for one-way real-time streaming (such as LLM tokens) over standard HTTP.
- gRPC: Select only when high-frequency internal microservice throughput and binary CPU serialization outweigh developer velocity.
- GraphQL: Select as a Backend-For-Frontend (BFF) aggregator for heterogeneous mobile clients needing sparse field filtering.

## Complete Step-by-Step Curriculum
- [Lesson 01: What is a REST API?](/tutorials/01-what-is-rest-api): The 6 architectural constraints, statelessness, and uniform interface.
- [Lesson 02: HTTP Methods, Status Codes & Query Parameters](/tutorials/02-http-methods-and-status-codes): PUT vs POST deep dive, safe vs idempotent verbs, filtering, sorting, and sparse fieldsets.
- [Lesson 03: Designing Your First Production CRUD API](/tutorials/03-designing-first-crud-api): Resource-oriented URI modeling, plural nouns, and response envelopes.
- [Lesson 04: Cursor vs Offset Pagination](/tutorials/04-cursor-vs-offset-pagination): Benchmarks, O(log N) seek pointers, and avoiding database table scans.
- [Lesson 05: API Authentication](/tutorials/05-authentication-jwt-vs-oauth2): Why Basic Auth is deprecated, cryptographic API keys, JWT rotation, and OAuth 2.1 with PKCE.
- [Lesson 06: Rate Limiting & Resilience](/tutorials/06-rate-limiting-and-resilience): Token Bucket, RFC 6585 headers (429 Too Many Requests), and Circuit Breakers.
- [Lesson 07: Distributed Idempotency Keys](/tutorials/07-idempotency-keys-distributed-systems): Preventing duplicate payments and requests during network retries.
- [Lesson 08: Designing REST APIs for Autonomous AI Agents](/tutorials/07-ai-agent-rest-api-patterns): Strict JSON Schema validation, operationId design, and self-correcting error messages.

## Architectural References & Practice
- [Protocol Comparison](/compare): Head-to-head architectural decision matrix and historical timeline (1980 - 2026).
- [Case Studies](/case-studies): Teardowns of Stripe idempotency, GitHub webhooks, and OpenAI streaming.
- [Status Codes & RFC 9457](/reference/status-codes): Definitive HTTP status code directory and machine-readable error schemas.
- [Interactive Quizzes](/exercises): 8 scenario-based challenges testing real-world architectural judgment.
- [Live Playground](/playground): Browser sandbox to simulate REST requests, headers, and response payloads.
- [Learning Tracks](/tracks): Level-based progression from beginner foundations to staff architect.