Lectures

We break down HTTP as a “contract” between a client and a server: what an endpoint consists of (a method + path pair), what the basic methods mean ( GET, POST, PUT, PATCH, DELETE), how to read status codes ( 200/ 201/ 204, 400/ 404, 500), and why you should think about idempotency—so repeated requests do not break state. At the end, we lock in a draft API contract for tasks and go over common design mistakes.

We lock down a practical JSON contract for an HTTP API: how to separate the roles of the Content-Type and Accept headers, why it’s better not to “expose” your domain model to the outside world and to move the external format into DTOs (for example, TaskDTO, CreateTaskRequest), and how to standardize errors via a single envelope ErrorEnvelope with a code ( error.code), a message ( error.message), and field-level validation errors ( error.fields). We verify JSON examples “in a vacuum” using json.MarshalIndent.

We break down HTTP API resource design using tasks as an example: the collection /api/v1/tasks, the individual resource /api/v1/tasks/{id}, the state /done, why it matters to pin the version /api/v1, and how to keep the path vocabulary consistent. At the end: an “API map” in Go code and common mistakes that break the contract.

Let’s break down why, in Go projects, it’s worth separating the domain model from DTOs: how not to “soak” the domain with json tags, where to keep invariants and business rules, why the outside world loves null and omitempty, and how to do explicit mapping with simple functions ( ToTaskDTO, ToCreateTaskInput). At the end — a decision cheat sheet and common mistakes when separating layers.

We break down why API documentation is part of the API contract, how to think in a contract-first way, how to format “endpoint cards”, and how to write copy-pastable curl examples. We lock in the base URL, statuses ( 201/ 204/ 404), a unified error envelope, and also show a practical approach to keeping DTOs and JSON examples in sync in Go via encoding/json and example generation.