What You Will Build

Here are the five endpoints the finished API exposes. Each pairs an HTTP verb with a path, and each returns a specific success status code. (A status code is the three-digit number HTTP uses to say how a request went. 2xx means success; 200 OK, 201 Created, and 204 No Content are the three we use here.)

A few things worth noticing now, because they come back later.

The verb carries the intent. GET reads, POST creates, PUT replaces, DELETE removes. The path names what you are acting on; the verb says what to do with it. That is the core idea of REST.

The {id} in three of the paths is a placeholder for a real task's ID, like GET /tasks/42. The same path with a different verb does a different thing, which is why routing requests to the right handler gets its own chapter later.

The status codes are not interchangeable. Create returns 201 (something new exists), a successful read or update returns 200 (here is the result), and delete returns 204 (it worked, and there is nothing to send back). Choosing the right one is part of building an API that other developers can trust, so we will be deliberate about it.

The Task resource

Every task the API stores and returns looks like this:

The fields:

• id — a unique number the server assigns when the task is created. The client never picks it.
• title — a short summary of the task. This is the one required field.
• description — optional longer detail. It can be empty.
• done — true or false, whether the task is finished. New tasks start false.
• createdAt — a timestamp set by the server when the task is created, in the standard UTC format you see above.

Notice that the server, not the client, owns id and createdAt. When you create a task you do not send those; the server fills them in and hands the complete task back. That keeps IDs unique and timestamps honest, and it is a small design decision you will see pay off when we write the create endpoint.

A create request, end to end

To make the JSON concrete, here is what creating a task looks like from both sides.

You send a POST to /tasks with just the fields you control:

The server stores it and replies with 201 Created and the full task, now including the id, the done flag defaulted to false, and the createdAt it stamped on:

That round trip, JSON in and JSON out, is the heartbeat of the whole service. Every endpoint is a variation on it.

How a request flows through the service

When a request arrives, it does not hit one giant block of code. It passes through a few clear layers, each with one job. Keeping these separate is what makes the service easy to test and easy to change later.

Reading left to right:

• Client — whatever made the request: curl, a browser, an app. It sends an HTTP request and waits for a response.
• HTTP server — Go's built-in web server. It reads the raw request, figures out which handler matches the verb and path, and turns the JSON body into Go values. When the work is done, it writes the JSON response and status code back.
• Service — the business logic. It decides what a valid task is, assigns the ID and timestamp, and orchestrates the work. It does not care how tasks are stored.
• Store — where tasks actually live. This is the layer we swap out partway through the course.

That last layer is the one to watch. We begin with an in-memory store: tasks held in a Go map that lives only while the program runs. Restart the server and they are gone. It is the simplest possible storage, which lets us focus on HTTP and JSON without a database in the way. Later we replace it with PostgreSQL, a real relational database, so tasks survive restarts.

Here is the part that makes the layering worth the effort: the service and HTTP layers will not change when we swap the store. They talk to storage through a single shared definition of what a store must do, so the in-memory version and the Postgres version are interchangeable. We will lean on that seam more than once, and it is one of the most useful ideas in the whole course.

The build, step by step

We do not build all of this at once. The course adds one capability at a time, in the order a real project tends to grow.

1. Language foundations. Before any of the API, we cover the Go you need to write it: types, structs, slices and maps, interfaces, errors, and a first look at concurrency. Small, runnable examples, no web server yet.
2. Your first HTTP server. We start the smallest possible server with the standard library and respond to a request, then layer on handlers, routing, and JSON until we can speak HTTP fluently.
3. In-memory CRUD. We build all five endpoints against the in-memory store. The API works end to end, just without a database behind it. This is where the resource shape and status codes above become real code.
4. Tests. Before we add a database, we test what we have built. Testing first here is on purpose: it builds the habit, and the test suite is what tells us later that swapping in Postgres did not break anything.
5. PostgreSQL. We bring in a real database, connect to it from Go, manage its schema, and move the store from memory to SQL. The endpoints stay the same; only the storage underneath changes.
6. Production concerns. Finally we make it shippable: request logging and panic recovery, configuration from the environment, structured logging, graceful shutdown, and a small Docker image that packages the whole thing.

You may have noticed we write tests before adding the database. That ordering is deliberate. It is easier to learn testing against the simple in-memory version, and once the tests exist they act as a safety net for the bigger change that follows. Throughout, we build the service the way it is done in production, not as a toy that happens to run.

What's Next

Enough planning. In the next chapter we install Go, set up your editor, and run your first program, so the toolchain is ready before we write any of the API.