POST Method in REST API Explained with Examples

The POST method in REST API is used to create new resources on a server. It is one of the most commonly used HTTP methods in web applications and APIs.

When you register a user, place an order, submit a form, create a support ticket, or trigger a payment transaction, the application typically sends a POST request to the server.

Unlike the idempotent GET method, a POST request can produce different results every time it is executed. Sending the same POST request multiple times may create multiple resources or trigger multiple actions.

Understanding how POST works is essential if you are building or consuming REST APIs.

What Is the POST Method in REST API Used For?

The POST method allows a client to send data to a server for processing.

Developers commonly use POST requests for:

Creating a new user account
Creating blog posts or comments
Submitting contact forms
Processing online payments
Uploading files
Creating Kubernetes resources through an API
Triggering asynchronous jobs and workflows

Unlike some other HTTP methods, POST requests typically include data inside the request body.

Common Examples of POST Requests

A few real-world examples include:

Creating a GitHub issue
Creating a customer record in a CRM
Registering a new user
Submitting an e-commerce order
Sending a message through a chatbot API

How the POST Method Fits into HTTP Methods

POST is one of several HTTP methods used by REST APIs.

If you are new to API design, read the guide on HTTP methods in REST API to understand when to use GET, POST, PUT, PATCH, DELETE, HEAD, and other methods.

A quick comparison:

GET retrieves data.
POST creates resources or triggers actions.
PUT replaces an existing resource.
PATCH partially updates a resource.
DELETE removes a resource.

Anatomy of a POST Request

A POST request contains several important components.

HTTP Method

The request starts with the HTTP verb:

POST

Endpoint or URI

The endpoint identifies where the request should be sent.

Example:

/api/users

If you need a refresher on identifiers used in APIs, see URL vs URI vs URN.

Headers

Headers provide metadata about the request.

Common POST request headers include:

Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json

To learn more about API headers, read response header in REST API.

Request Body

The request body contains the data being sent to the server.

Most modern APIs use JSON because it is lightweight and easy to parse.

Example:

{
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "age": 30
}

For a deeper understanding of API communication, see anatomy of REST API request and REST API request and response pair.

Example of a POST Request

The following example creates a new user resource.

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

{
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "age": 30
}

The client sends user information to the server, and the server processes the request to create a new resource.

Example Response Returned by a POST Request

When a resource is successfully created, servers typically return the HTTP status code 201 Created.

Example:

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

{
  "id": 12345,
  "name": "Alice Johnson",
  "email": "alice@example.com"
}

The Location header identifies the newly created resource.

Common Success Status Codes

A POST request may return:

201 Created — A new resource was successfully created.
200 OK — The request completed successfully.
202 Accepted — The server accepted the request for asynchronous processing.
204 No Content — The operation succeeded but no response body is returned.

For additional status code explanations, read:

Common Error Status Codes

A POST request may also return:

400 Bad Request — Invalid request syntax or payload.
401 Unauthorized — Authentication is required.
403 Forbidden — Access is denied.
404 Not Found — Resource endpoint does not exist.
409 Conflict — Resource conflict occurred.
422 Unprocessable Content — Validation failed.

The official HTTP semantics documentation is maintained by the IETF HTTP Working Group.

POST vs PUT: Understanding the Difference

Developers often confuse POST and PUT.

POST is generally used when creating a resource and the server determines the resource identifier.

PUT is generally used when replacing an existing resource and the client already knows the target resource.

For example:

POST Example

POST /api/users

The server creates a new user and assigns an ID.

PUT Example

PUT /api/users/12345

The client updates or replaces the resource with ID 12345.

To learn more, read the complete guide on PUT method in REST API.

If you only need to update specific fields, the PATCH method in REST API is usually a better choice.

Best Practices for Using POST Requests

Validate Request Data

Never trust incoming data.

Validate:

Required fields
Data types
String lengths
Email formats
Business rules

Input validation helps prevent security vulnerabilities and application errors.

Use Appropriate Status Codes

Return meaningful HTTP status codes so API consumers can easily understand the outcome.

Avoid returning 200 OK for every scenario.

Secure Your POST Endpoints

POST endpoints often modify data and therefore require proper security controls.

Use:

Authentication
Authorization
Rate limiting
Input validation
HTTPS encryption

For more details, see REST API authorization and authentication.

The OWASP API Security Project provides industry-standard API security guidance.

Document Accepted Content Types

Clearly define supported formats such as:

application/json
application/xml
multipart/form-data

API consumers should know exactly what payload format the server expects.

Handle Duplicate Requests Carefully

POST requests are generally non-idempotent.

If the same request is accidentally submitted multiple times, it may create duplicate resources.

Production systems often implement:

Idempotency keys
Request deduplication
Transaction safeguards

These techniques are especially important in payment systems.

Practical Request Flow

A typical POST workflow looks like this:

Client sends a POST request.
Server validates the request.
Server processes the data.
Server creates a resource or performs an action.
Server returns a success or error response.

This pattern forms the foundation of many REST-based systems.

Frequently Asked Questions

Can I use POST for both creating and updating resources?

Yes, but it is generally better to follow REST conventions.

Use:

POST for creating resources
PUT for full replacements
PATCH for partial updates

Following these conventions makes APIs easier to understand and maintain.

Is POST idempotent?

No.

A POST request is typically non-idempotent because repeating the same request may create additional resources or trigger additional actions.

How do I protect POST endpoints from unauthorized access?

Implement authentication and authorization mechanisms such as:

OAuth 2.0
JWT
API keys
Session-based authentication

You can learn more from the official OAuth 2.0 documentation.

Can POST requests send large amounts of data?

Yes.

Large payloads can be handled through:

Compression
Chunked uploads
Multipart requests
Streaming techniques

The best approach depends on your API design and infrastructure requirements.

Does every POST request create a resource?

No.

POST can also trigger actions such as:

Sending emails
Starting workflows
Processing payments
Running background jobs

Resource creation is common, but it is not the only use case.