201 Created

Description

The 201 Created status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. This status code is typically returned in response to a POST request or some PUT requests.

The primary resource created by the request is identified by either a Location header field in the response or, if no Location field is received, by the effective request URI. The 201 response typically includes an entity containing a status report and description of the new resource(s).

This status code is commonly used in RESTful APIs when creating new resources, such as user accounts, database records, or file uploads.

Syntax

The server responds with a 201 Created status and typically includes a Location header pointing to the newly created resource:

HTTP/1.1 201 Created
Location: /resource/identifier
Content-Type: [appropriate media type]
Content-Length: [length in bytes]

[Response body containing information about the created resource]

Examples

User Registration Example

A client submits a new user registration:

Client Request:

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 98

{
  "username": "johndoe",
  "email": "[email protected]",
  "password": "securepassword123"
}

Server Response:

HTTP/1.1 201 Created
Location: /users/12345
Content-Type: application/json
Content-Length: 157

{
  "id": 12345,
  "username": "johndoe",
  "email": "[email protected]",
  "created_at": "2023-06-15T14:30:22Z",
  "status": "active"
}

File Upload Example

A client uploads a new file:

Client Request:

POST /files HTTP/1.1
Host: storage.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Length: 5782

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf

[Binary PDF data]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Server Response:

HTTP/1.1 201 Created
Location: /files/f47ac10b-58cc-4372-a567-0e02b2c3d479
Content-Type: application/json
Content-Length: 198

{
  "file_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "filename": "document.pdf",
  "size": 4218,
  "content_type": "application/pdf",
  "created_at": "2023-06-15T15:45:12Z",
  "download_url": "/files/f47ac10b-58cc-4372-a567-0e02b2c3d479/download"
}

Resource Creation in RESTful API

A client creates a new blog post:

Client Request:

POST /api/posts HTTP/1.1
Host: blog.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Length: 253

{
  "title": "Understanding HTTP Status Codes",
  "content": "HTTP status codes are three-digit numbers that indicate the outcome of an HTTP request...",
  "tags": ["http", "web", "programming"],
  "publish": true
}

Server Response:

HTTP/1.1 201 Created
Location: /api/posts/5678
Content-Type: application/json
Content-Length: 387

{
  "id": 5678,
  "title": "Understanding HTTP Status Codes",
  "content": "HTTP status codes are three-digit numbers that indicate the outcome of an HTTP request...",
  "author_id": 12345,
  "created_at": "2023-06-15T16:20:45Z",
  "published": true,
  "url": "https://blog.example.com/posts/understanding-http-status-codes",
  "tags": ["http", "web", "programming"]
}

Summary

The 201 Created status code is used to indicate successful resource creation. It provides confirmation that the server has fulfilled the client's request to create a new resource, and typically includes information about how to access that resource via the Location header. This status code is an essential part of RESTful API design and is commonly used when implementing create operations in CRUD (Create, Read, Update, Delete) functionality.