Stage 3 · Build

HTTP & REST APIs

HTTP Fundamentals

Methods, status codes, headers, content negotiation, and idempotency for predictable APIs.

7 min readBuilding Backend ApplicationsBuild

Request-Response Model

HTTP is a stateless, text-based protocol where a client sends a request and the server returns a response. Every interaction is independent, the server stores no client state between requests. This simplicity is what makes HTTP scalable and cacheable.

A request consists of a method, URI, headers, and an optional body. The response carries a status code, headers, and a body. Understanding this structure is essential for building APIs that behave predictably.

HTTP Methods

Each method has a defined semantic meaning. Choosing the right method communicates intent and enables correct behavior from caches, proxies, and clients.

Method	Purpose	Idempotent	Body
GET	Read a resource	Yes	No
POST	Create a resource or trigger action	No	Yes
PUT	Replace a resource entirely	Yes	Yes
PATCH	Partially update a resource	No	Yes
DELETE	Remove a resource	Yes	No

Idempotency matters

An idempotent method produces the same result whether called once or multiple times. GET, PUT, and DELETE are idempotent. POST and PATCH are not. This distinction is critical for retry logic and safe network behavior.

Status Codes

Status codes tell the client what happened. They group into five classes, each prefixed with a digit from 1 to 5. Using the correct code lets clients handle responses programmatically.

Range	Class	Common Examples
1xx	Informational	100 Continue, 101 Switching Protocols
2xx	Success	200 OK, 201 Created, 204 No Content
3xx	Redirection	301 Moved, 304 Not Modified
4xx	Client Error	400 Bad Request, 401 Unauthorized, 404 Not Found
5xx	Server Error	500 Internal Error, 502 Bad Gateway, 503 Unavailable

Goreturning-proper-status-codes-in-go.go

17 linesLn 1, Col 1Go

Always return the most specific status code. 201 Created for new resources, 204 No Content for successful deletes, 400 for validation errors.

Headers

Headers carry metadata about the request or response. They control caching, authentication, content type, and connection behavior. Some headers are required, others optional but strongly recommended.

Content-Type tells the client what format the body uses.
Authorization carries credentials for authenticated requests.
Cache-Control instructs caches how to handle the response.
ETag provides a version identifier for conditional requests.
X-Request-ID enables distributed tracing across services.

Content Negotiation

Content negotiation lets the client and server agree on a response format. The client sends Accept headers indicating preferred formats, the server picks the best match. For REST APIs, application/json is the standard.

Gochecking-accept-header-in-go.go

11 linesLn 1, Col 1Go

Most APIs only support JSON. If a client requests an unsupported format, return 406 Not Acceptable.

Idempotency

Network failures happen. Clients will retry requests. If a POST creates a duplicate resource on retry, your API is broken. Idempotency keys solve this by letting the server recognize duplicate requests.

Goidempotency-key-pattern.go

24 linesLn 1, Col 1Go

Store the idempotency key with a TTL. On subsequent requests with the same key, return the stored response instead of processing again.

Use UUIDs for idempotency keys

Generate idempotency keys with uuid.New().String(). Store them in Redis with a 24-hour TTL. This prevents duplicate resource creation even when clients retry rapidly.

Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.