RESTful Web Service 為現在流行,用來存取資料庫記錄的 API 設計形式。以下以 JSON 資料交換格式為例,展示幾種對記錄進行增查改刪 (CRUD, Create, Read, Update, Delete) 運算時,常用的 HTTP 請求及回應範例。
設計 RESTful API 時,請求參數如果量小,可以利用 Path Parameter, Query String Parameter, Header Parameter, Body Parameter using application/json, Body Parameter using application/x-www-form-urlencoded 等參數傳遞法。如果參數量大,包含檔案,則可利用 Body Parameter using multipart/form-data 參數傳遞法。
同樣的,回應結果如果量小,可以利用 application/json 結果回傳法。如果量大,包含檔案,則可利用 multipart/mixed 結果回傳法。
以下透過 MS Copilot 生成幾種可能的 HTTP 請求及回應長相,如下。
(一) 利用 HTTP 進行新增及查詢記錄的幾種作法如下: A. 請求(Request)訊息格式 A1: Path Parameter 由路徑上的id,查詢某人基本資料GET /api/users/123 HTTP/1.1 Host: example.com Accept: application/json
A2: Query String Parameter 由查詢字串上的id,查詢某人基本資料GET /api/users?id=123 HTTP/1.1 Host: example.com Accept: application/json
A3: Header Parameter 由標頭區的id,查詢某人基本資料GET /api/users/123 HTTP/1.1 Host: example.com Accept: application/json id: 123
A4: Body Parameter using application/json 由本體區的id,查詢某人基本資料POST /api/users HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/json Content-Length: 18 { "id": 123 }
A5: Body Parameter using application/x-www-form-urlencoded 新增某人基本資料POST /users/updateProfile HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/x-www-form-urlencoded Content-Length: 27 id=123&name=John+Doe&email=johndoe%40example.com
A6. Body Parameter using multipart/form-data 新增某人基本資料,含照片POST /users/uploadProfile HTTP/1.1 Host: example.com Accept: application/json Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Length: [length] ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="metadata" Content-Type: application/json { "id": 123, "name": "John Doe", "email": "johndoe@example.com" } ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Disposition: form-data; name="profileImage"; filename="profile.jpg" Content-Type: image/jpeg
[image data here] ------WebKitFormBoundary7MA4YWxkTrZu0gW--B. 回應(Response)訊息格式 B1. application/json格式,回傳某人基本資料HTTP/1.1 200 OK Content-Type: application/json Content-Length: 85 { "id": 123, "name": "John Doe", "email": "johndoe@example.com" }B2. multipart/mixed格式,回傳某人基本資料,含檔案HTTP/1.1 200 OK Content-Type: multipart/mixed; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW Content-Length: [total length] ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Type: application/json{ "id": 123, "name": "John Doe", "email": "johndoe@example.com" } ------WebKitFormBoundary7MA4YWxkTrZu0gW Content-Type: application/octet-stream Content-Disposition: attachment; filename="example.txt"[file data here] ------WebKitFormBoundary7MA4YWxkTrZu0gW--(二) 利用 HTTP 進行修改及刪除記錄的作法如下: A. 修改記錄 Request:PUT /api/users/123 HTTP/1.1 Host: example.com Accept: application/json Content-Type: application/json Content-Length: 58 { "name": "Jane Doe", "email": "janedoe@example.com" }
Response:HTTP/1.1 200 OK Content-Type: application/json Content-Length: 85{ "id": 123, "name": "Jane Doe", "email": "janedoe@example.com", "status": "updated" }B.刪除記錄 Request:DELETE /api/users/123 HTTP/1.1 Host: example.com Accept: application/json
Response:HTTP/1.1 200 OK Content-Type: application/json Content-Length: 45 { "id": 123, "status": "deleted" }