REST (Representational State Transfer) is an architectural style for creating web services. REST APIs allow client applications to access and manipulate resources hosted on a server. REST uses HTTP methods to define operations on resources. The main HTTP methods used are GET, POST, PUT, PATCH, and DELETE.
The POST method is commonly used in REST APIs to create new resources on the server. So the short answer is – yes, we can use POST in a REST API.
What is POST method in REST API?
The POST method is used to create a new resource on the server. When a POST request is sent to a REST API, the request body contains the data for the new resource to be created. This data is parsed by the API and used to create the resource.
For example, let’s say we have a REST API to create new user accounts. A client application can send a POST request to /users with the new user data in the request body. The API would take this data, validate it, and create a new user resource. It would return a 201 Created status on success along with the URL of the newly created resource.
Key characteristics of POST method:
- Used to create a new resource
- Request body contains details of resource to be created
- Returns 201 Created status code on success
- Returns location of newly created resource in response
- Should not be idempotent – multiple identical requests create new resources
When to use the POST method?
Here are some common scenarios when the POST method should be used in a REST API:
1. Creating new resources
As explained earlier, POST is designed to create new resources on the server. So any time there is a requirement to allow clients to create new resources, POST should be used.
2. Executing state-changing operations
POST can also be used to execute operations that change state on server but do not exactly create a new resource. For example, placing an order, making a payment, adding a like, etc. These operations change state but may not create a new resource.
3. Running server-side processes
POST can trigger long-running processes on the server. The request sends input data to start the process and the server returns a unique identifier. Client can use this ID to check status of the operation.
Advantages of using POST
Here are some key advantages of using the POST method in your REST APIs:
- Semantics: POST clearly indicates that this request is for creating new resources. This improves understandability.
- Request body: POST allows including all required data for creating resource in request body. No need for long query params.
- Non-idempotent: Since multiple POST requests create new resources, there are no side-effects of clients retrying requests.
- Status codes: POST response contains standard status codes to indicate outcomes – 201 for created, 4xx for client errors, 5xx for server errors.
Limitations of POST method
However, the POST method also comes with some limitations:
- No caching: POST responses are typically not cached as the request changes state on server.
- Bookmarks: The newly created resource URL cannot be bookmarked as POST is not idempotent.
- Retries: Clients need special logic to handle retries as duplicate requests may create unwanted resources.
- Restricted: Some firewalls block POST requests, so APIs may have to use GET instead.
Best practices for using POST API
Here are some best practices to keep in mind when designing POST APIs:
1. Validate request structure
The API should validate that the POST request contains all required data fields in the expected format. Return 400 Bad Request error for any validation failures.
2. Validate request size
Check for any size limits on POST body and reject large requests with 413 Payload Too Large response.
3. Authenticate user
Verify identity of user before allowing creation of resources. Return 401 Unauthorized if authentication fails.
4. Check user permissions
The API should check if user has required permissions before creating resource. Return 403 Forbidden for any authorization failures.
5. Handle duplicates
Check for duplicate requests and have logic to avoid creating duplicate resource. Return appropriate error message to user.
6. Return resource URL
The response should contain Location header with URL of the newly created resource.
7. Use appropriate status codes
Follow standard HTTP guidelines and return proper status codes – 201 on success, 4xx for client errors and 5xx for server errors.
PUT vs POST – Key Differences
Both PUT and POST can be used for creating resources in REST API. However there are some key differences:
| PUT | POST |
|---|---|
| Idempotent – Making multiple identical requests has same effect as single request | Not idempotent – Making multiple identical requests creates multiple resources |
| Used to update existing resource when URI is known | Used to create new resource when URI is not known beforehand |
| Requires complete resource details in request | Requires only data needed to create resource |
| Returns 200 OK on success | Returns 201 Created on success |
POST vs PUT – When to use each?
Based on the differences summarized above, here is when POST and PUT should be used:
- Use PUT when URL of resource to be updated is known. PUT replaces entire resource with provided data.
- Use POST when creating a new resource where URL is not known in advance. POST creates resource with provided data.
- Use POST to execute controllers or handlers that change state but do not return a resource URL.
- Use PUT when performing full replacement of a resource. POST can do partial updates.
- Use POST for non-idempotent write operations. Use PUT for idempotent update operations.
Conclusion
POST is an essential method in designing REST APIs. It allows clients to create new resources on the server. Using POST improves understandability over GET and provides better structure via request body. However, care must be taken to implement POST handlers properly by validating requests, checking permissions, handling errors, etc.
In summary, POST is a great fit for non-idempotent resource creation, state-changing operations and long-running processes. Understanding the difference between POST and PUT helps pick the right method for specific API use cases.