請辭後三十日冷河期, 除了寫document handover 外, 唯有聽talk 裝備自己. 在此摘錄重點.
| 講題 | Never RESTing – RESTful API Best Practices using ASP.NET Web API – |
| 講者 | Spencer Schneiden bach: (blog: rest.schneids.net) |
| 頻道 |
定義
- RESTful API : API 跟從REST 架構
- REST不等如JSON API
- RESTful 不等如最好, 要因時制宜
大原則: KISS (Keep It Simple Stupid)
- 不要太畫蛇添足;
- 只傳回足夠資訊, 不多不少;
- 避免利用API 傳回值去搜尋另一API;
- 利用HTTP status code, 例如:
- 200: OK
- 201: Created
- 400: Bad Request
- 404: Not Found
- 401: Unauthenticated (沒有權限)
- 403: Forbidden (不能做)
大原則: Be consistent with accepted best practices / yourself
- 與業界標準及自己practices 相對應, 非必要不要太有獨創性, 令人難以使用.
- 利用HTTP request verb:
- GET: 讀取資料;
- POST: 加入新資料;
- PUT: 更新資料;
- DELETE: 移除資料;
- PATCH: 與PUT 一樣更新資料, 但不用傳回所有資料;
- 不要濫用HTTP GET;
- Be consistent, but be flexible if it makes sense;
命名: Nouns vs Verb
| Nouns | Verb | |
| 例子 | GET /employees /employees/123 | GET /getAllEmployees /getEmployeeWithId |
| POST /employee | POST /createEmployee |
- 用眾數 (plural);
- Sub resources (是否須要傳回有關係的resources)
- 在URL 中設定
- GET /customer/1234/invoices
- GET /customer/1234?expand=invoices
HTTP GET 的考量
Sorting
GET https:/aaa.com/v1.0/people?$orderBy=name
$orderBy=name desc
$orderBy=name desc,hireDate
Filtering
GET https:/aaa.com/v1.0/people$filter=name eq ‘mike’
Google OData web api
Paging
限制讀取數量
GET https:/aaa.com/v1.0/people?page=1&pageSize=1000
{
pageNUmber=1, result: […], nextPage:” https:/aaa.com/v1.0/people?page=2”
}
是否必需? 可能, 須因地制宜
Versioning
- 必須有test;
- 於header 中加入X-Api-Version;
- 在URL 中加入version number;
錯誤報告
- 須有HTTP code;
- 有API 內部的error code 及message;
- 有與error code 相關的document 用作troubleshooting;
- 令consumer 容易找出問題及除錯;
Security
Encryption
- 用SSL;
- 不要用自行定義的encryption;
Authentication
- 利用token based authentication;
Code Practice
- 不要太倚靠auto gen;
- 用DTO 在存取request, 及進行validation;
Separation of Concerns
- Controller 角色為traffic control, 決定refer 去邊度做嘢, 而非executer;
- 必須validate 所有request, 並將validation logic 從object 分開
- 有用library: FluentValidation
Architecture
Controller -> Request -> Validator > Handler / Service
有用library: MediatR
Documentation
- 決定API 質素
- Endpoint: List of endpoints;
- Parameter: Endpoint 需要的parameter;
- Schema: 資料傳入及傳出 (e.g. JSON / XML)
- Formatting: e.g. Date (ISO 8601)
- Error: 如何manage Exception
維護API
- 修補錯誤及改善效能
- 不要有backward incompatible change;
Leave a Reply