POST: Creating Resources
You'll learn how to use the HTTP POST method to create new resources, interpret server responses, and understand the 201 Created status code.
What POST Does
POST is the HTTP method for creating new resources on the server. Think of it like submitting a completed form at a government office—you're providing data to create a new record in their system, and they give you a receipt with details about what was created.
Unlike GET (which only retrieves existing data), POST sends data in the request body to tell the server what resource to create. The server decides where to place this new resource and assigns it an identifier.
Request Structure
When you POST to create a resource, you send to a collection endpoint (e.g., /api/users), not a specific resource. The request includes:
- Target URI: The collection where the resource belongs
- Request Body: The data for the new resource (usually JSON)
- Content-Type Header: Tells the server the format (e.g.,
application/json)
Example: POSTing {"name": "Alice", "email": "alice@example.com"} to /api/users
Understanding 201 Created
When successful, the server responds with 201 Created status code—not 200 OK. This specifically signals that a new resource was created. The response typically includes:
- Location Header: The URI of the newly created resource (e.g.,
/api/users/42) - Response Body: Often the complete representation of the created resource, including server-generated fields like
idandcreatedAt
This lets your frontend immediately know where the resource lives and what its final state is.
Key Takeaway: POST creates new resources at collection endpoints, returning 201 Created with the Location header pointing to the new resource's URI and typically including the full resource representation in the response body.