[ADP-112] POST

概述

HTTP POST 方法用於向伺服器發送數據以創建資源。通過 POST 發送到伺服器的數據包含在請求主體中。常見用例包括表單提交、文件上傳和其他需要伺服器端處理的操作。此外，POST 可以用於使用 /resources/action 模式對資源執行特定操作，以補充其他 HTTP 方法的限制。

指導原則

POST 請求必須(MUST)用於創建資源。
可以(MAY)使用 POST /resources/action 模式來執行不適用標準 CRUD 操作的特定資源操作。
- 必須(MUST)清楚定義和記錄通過此模式可用的操作，以確保清晰性和一致性。
數據應該(SHOULD)以 JSON 格式(Content-Type: application/json)提交。
如有必要，應(SHOULD)支持冪等性，參見應支持冪等性。
- 不得(SHOULD NOT)假設 POST 請求是冪等的。多個相同的請求可能會導致不同的結果。
- 客戶端應(SHOULD)避免使用 POST 進行每次相同請求需要產生相同結果的操作。
- 客戶端應(SHOULD)決定是否要讓 POST 冪等。
必須(MUST)設置 Content-Type 標頭以指示正在發送的資源的媒體類型(例如，application/json)。
應(SHOULD)使用適當的身份驗證和授權標頭(例如，Authorization: Bearer <token>)。
成功的創建類 POST 請求應(SHOULD)返回 201 Created 狀態碼，以及指示新創建資源 URL 的 Location 標頭。
如果出現錯誤，必須(MUST)返回適當的狀態碼，如 400 Bad Request 或 500 Internal Server Error，並附帶遵循 HTTP Problem 格式的描述性錯誤消息。關於 HTTP 錯誤的詳細資訊，請參見錯誤設計。
比起查詢參數，應(SHOULD)優先使用請求主體(payload)傳遞數據。

請求負載大小

DRAFT 伺服器應(SHOULD)實施合理的 POST 請求負載大小限制，以防止濫用。
DRAFT 應(SHOULD)在 API 規範中記錄允許的最大負載大小。

如果請求超過大小限制，伺服器應回應 413 Payload Too Large 狀態碼並遵循 HTTP Problem 格式。

413 回應示例:

http

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

{
  "type": "https://example.com/problems/payload-too-large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "10MB 的請求負載超過了允許的最大大小 5MB。",
  "instance": "/users"
}

示例

創建新資源

http

POST /users HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer <token>

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "securepassword"
}

回應:

http

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"
}

執行特定操作

http

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

{
  "newPassword": "newsecurepassword"
}

回應:

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "密碼已成功重置。"
}

Accept-Post 標頭

參閱 ADP-146。

參考

Changelog

2024.09.24 Remove unwanted /api path in the samples; use password-reset to be sync with other ADP.

[ADP-112] POST ​

概述 ​

指導原則 ​

請求負載大小 ​

示例 ​

Accept-Post 標頭 ​

參考 ​

Changelog ​

[ADP-112] POST

概述

指導原則

請求負載大小

示例

Accept-Post 標頭

參考

Changelog