API tutorial

Build a real coffee-shop API in your browser: design the contract, then make it documented, versioned, secure and fast, and learn when to use GraphQL or gRPC instead.

Start the course

Course contents

REST Foundations

  1. Introduction to APIs — Learn what an API is, how a client and a server talk through requests and responses, and why every API is a contract. Break one and fix it in your browser.
  2. HTTP Basics — Read every line of a real HTTP request and response: the method, path, query string, headers and JSON body, and why a missing Content-Type breaks a request.
  3. HTTP Methods — Learn GET, POST, PUT, PATCH and DELETE, what safe and idempotent mean, and how an Idempotency-Key stops a retried payment from charging twice.
  4. REST API Design and URL Naming — Turn action-style endpoints into clean REST resource URLs, nest related resources, and add filtering, sorting and capped pagination with the query string.
  5. HTTP Status Codes and Error Handling — Make every reply tell the truth: choose the right status code, stop hiding errors inside 200 OK, and send errors as Problem Details (RFC 9457).
  6. Request Validation and DTOs — Stop bad data at the door: use request and response DTOs, block over-posting, validate every field, and return every error as a validation problem.
  7. Building a CRUD API — Build create, read, update and delete endpoints for the menu and orders, guard status changes with 409, and move logic into services.
  8. API Documentation with OpenAPI — Describe your API in an OpenAPI document, serve it from ASP.NET Core, and use it to list endpoints, lint the design, contract-test responses and generate clients.

Production-Ready APIs

  1. API Versioning — Change an API without breaking its clients: spot breaking changes, serve /v1 and /v2 side by side, and retire old versions with Deprecation and Sunset headers.
  2. API Authentication — Make the API ask who is calling: protect endpoints with API keys, read and validate JWT bearer tokens, and answer 401 with WWW-Authenticate.
  3. API Authorization and Security — Check on every request that the caller is allowed to do this: own the record, have the role, carry the scope.
  4. API Performance and Caching — Make your API fast by not repeating work: fix N+1 queries, answer repeat visits with 304, and tell caches what they may keep.
  5. Rate Limiting and Resilience — Protect your API from too much traffic with rate limits and 429 Too Many Requests, and make clients cope with slow or failing services using retries and backoff.
  6. API Monitoring and Logging — Use structured logs, correlation ids, health checks and RED metrics to see what your API is doing and find bugs fast.
  7. API Testing — Write automated unit and integration tests that check status, headers and body on every change, so a fixed bug never comes back.
  8. API Gateway — Put one front door in front of your services so auth, limits, routing and header rules happen once, in one place.

Beyond REST

  1. GraphQL — Let the client ask for exactly the fields it needs, in one request, with a GraphQL query.
  2. gRPC — Let services talk fast with small binary protobuf messages and a strict .proto contract.
  3. REST vs GraphQL vs gRPC — Start with REST, and pick GraphQL, gRPC, webhooks or Server-Sent Events only when you have a clear reason.
  4. Capstone Project: Loyalty Points API — Build a complete Loyalty Points API for Brew & Bytes: validated, retry-safe, authorized, versioned, documented and monitored.

Reference

  1. API Cheat Sheet — One page with the methods, URL rules, error shape, headers and side-by-side C# and Hono snippets you reach for every day.
  2. HTTP Status Codes and Headers — Every status code and header used in the course, with what it means, when to send it and a one-line C# and Hono example.
  3. API Error Reference — Real error messages you will meet while building APIs, what causes each one, how to fix it and which lesson explains it.
  4. API Glossary — Every term from the course, A to Z, each explained in one or two plain sentences.