[ADP-112] POST

Overview

The HTTP POST method is used to send data to a server to create a resource. The data sent to the server with POST is included in the request body. Common use cases include form submissions, file uploads, and other operations requiring server-side processing. Additionally, POST can be used to perform specific actions on resources using the /resources/action pattern to supplement the limitations of other HTTP methods.

Guidance

• The POST request MUST be used to create resources.
• The POST /resources/action pattern MAY be used to perform specific actions on resources that do not fit neatly into standard CRUD operations.
  • The actions available via this pattern MUST be clearly defined and documented to ensure clarity and consistency.
• Data SHOULD be submitted in JSON format.
• SHOULD support idempotent if necessary, See SHOULD support Idempotent.
  • POST requests MUST NOT be assumed to be idempotent. Multiple identical requests may result in different outcomes.
  • Applications SHOULD avoid using POST for operations where the same request needs to yield the same result each time.
  • The client SHOULD decide whether to make POST idempotent.
• The Content-Type header MUST be set to indicate the media type of the resource being sent (e.g., application/json).
• Appropriate authentication and authorization headers SHOULD be used (e.g., Authorization: Bearer <token>).
• A successful POST request SHOULD return a 201 Created status code, along with a Location header indicating the URL of the newly created resource.
• For POST /resources/action operations that modify a resource, the server MAY return a 200 OK status code along with the full, updated representation of the resource. This provides the client with the most current state of the resource without requiring an additional GET request.
  • It's also viable to response 204 No Content if the resource is modified successfully.
  • SHOULD document depending on your strategy. You MAY use both.
• In case of errors, appropriate status codes MUST be returned, such as 400 Bad Request or 500 Internal Server Error, with descriptive error messages which follows HTTP Problem format. See Error Design.
• SHOULD prefer payload over query parameters for request data.

Request Payload Size

• Servers SHOULD implement reasonable size limits for POST request payloads to prevent abuse.
• The maximum allowed payload size SHOULD be documented in the API specifications.
• If a request exceeds the size limit, the server SHOULD respond with a 413 Payload Too Large status code and follow the HTTP Problem format.

Example of a 413 response:

HTTP/1.1 413 Payload Too Large
Content-Type: application/problem+json

{
  "type": "https://example.com/problems/payload-too-large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "The request payload of 10MB exceeds the maximum allowed size of 5MB.",
  "instance": "/users"
}

Example

1. Creating a New Resource

   POST /users HTTP/1.1
   Host: example.com
   Content-Type: application/json
   Authorization: Bearer <token>
   
   {
     "username": "newuser",
     "email": "newuser@example.com",
     "password": "securepassword"
   }

   Response:

   HTTP/1.1 201 Created
   Location: /users/123
   Content-Type: application/json
   
   {
     "id": 123,
     "username": "newuser",
     "email": "newuser@example.com",
     "createdAt": "2024-07-10T12:34:56Z"
   }

2. Performing a Specific Action

   POST /users/123/password-reset HTTP/1.1
   Host: example.com
   Content-Type: application/json
   Authorization: Bearer <token>
   
   {
     "newPassword": "newsecurepassword"
   }

   INFO

   For the pattern of multi-word action, please refer to ADP-306.

   Response:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "message": "Password has been reset successfully."
   }

Accept-Post header

Please refer ADP-146。

References

• RFC 9110: POST
• MDN Web Docs: POST
• REST API Tutorial: HTTP Methods
• Best Practices for Designing a Pragmatic RESTful API
• HTTP Status
• ADP-306

Changelog

• 2025.07.02 Add guidance on 200 OK/204 No Content responses for POST /resources/action operations.
• 2024.09.24 Remove unwanted /api path in the samples; use password-reset to be sync with other ADP.