Apiary design api flow (未完成) - fantasy0107/notes GitHub Wiki
Apiary design api flow
1. Preparation (準備階段)
Define domain semantics (定義領域語義)
- 列出所有會用到的名詞
- 讓每個人都知道每個字的意思
- 要清楚的定義每個字和意思這是基礎
Choose architectural style (選擇架構風格)
event-driven ? URI CRUD-based ? Hypermedia API ? 每個都各有優缺點
選擇一個合適的架構
Formalize style guide (正式化風格指南)
定義 conventions of your API
想像它是 API 的 coding style guide
例如
- media type you're going to use (使用哪種媒體)
- the kind of authentication you will put in place (使用哪種 authentication)
- the way you will paginate results (你 paginate 結果的方法)
- naming conventions (命名慣例)
- URI formatting (URI 格式)
2. Design & Prototype
定義 API 長怎麼樣
建立它的 stub 實作
確認它參與到整個工作流程
Identify Resources (辨認資源)
在 API 中要顯示那些資源(resources)
分解 領域名詞 哪些是 attribute 哪些是 action
建立 資料模型
將這些資料模型當作資源
Define resource stats (定義資源狀態)
可以知道哪些是資源
哪些是屬性
Write API Description
格式化 API 描述
用 Swagger 或 API Blueprint
- API’s architectural style
- resources
- relations
- API style guide
Use Apiary mock server
在實作之前先丟出假資料
Put API Description on GitHub
將 API description 分享給同事
- version
- share
- collaboration
- 建議在開發的時候用 Github flow
- 在 commit 的時下有意義的訊息
Share and Review
- 取得 feedback
- 確保 API descriptnio 是被贊同
- 何需要被修改的項目被條列式列出
- 發布 API Documentation
- 叫每個人看 API description 確保是符合 Style guide
- API description 是否被認可
- 當被認可就可以開始寫 code 去實作並且置換原本用 mock server 弄出來的東西
輔助工具 - Apiary
3. Development
輔助工具 - Postman
根據你的 (Design, Prototype Phase) 去實作 API
Put the API Description next to Implementation (實作)
- 確保你的 code 和你設計的是一致的
Develop Server (開發 Server)
- 選擇 programming language, framework 等等相關的
Test Server Locally (本地測試)
在本地端寫測試
Test Server in CI (持續性整合測試)
設定整合性測試去測試你的 API
Use Apiary Test Reporter (使用 Apiary 測試報告)
Deploy (部屬)
4. Delivery
當經過 開發, 測試和部屬後交付給客戶
輔助工具 - Swagger
Share the API Description (分享 API 描述)
Share Apiary Documentation (分享 Apiary 文件)
Embed Apiary Documentation (嵌入 Apiary 文件)
API Management (API 管理)
5. Consumption
你的 API 使用者將會建立他們的客戶端
Use Apiary Documentation (使用 Apiary 文件)
Use Apiary Documentation Console (使用 Apiary 文件 console)
Use Language Examples (使用語言範例)
Use Apiary Traffic Inspector (使用 Apiary Traffic Inspector)
Develop Client with Apiary Mock Server (用 Apiary Mock Server 開發客戶端)
Develop Client with Apiary Proxy (用 Apiary Proxy 開發客戶)
6. Analysis
測量你的 API 使用和聆聽任何 feedback
Collect the Feedback (收集 Feedback)
- Design and prototype phase - API product owners, organization architects and API consumers
- Development phase - 來自開發者 增進效能和安全
- Delivery and Consumptions - 測試
Iterate (重複之前的步驟)
- 分析每個階段的 Feedback
參考資料
範例
- 所有符號都要靠最左
- 支援 API Blueprint 和 Swagger
- 要縮排
Metadata, API Name & Description
一定要有 FORMAT 關鍵字
FORMAT: 1A
# Polls (Api文件名稱)
## Resource (資源)
### Get/Post/Patch/Delete 動作
+ 回應
+ Parameters
+ question_id (required, Number, `1`) ... 提問的編號。
## Question Collection [/questions]
範例
範本
前置
# dodog
## Questions Collection [/questions]
Get
### List All Questions [GET]
+ Response 200 (application/json)
[
{
"question": "Favourite programming language?",
"published_at": "2015-08-05T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"votes": 2048
}, {
"choice": "Python",
"votes": 1024
}, {
"choice": "Objective-C",
"votes": 512
}, {
"choice": "Ruby",
"votes": 256
}, {
"choice": "PHP",
"votes": 987
}
]
}
]
Post
### Create a New Question [POST]
You may create your own question using this action. It takes a JSON
object containing a question and a collection of answers in the
form of choices.
+ Request (application/json)
{
"question": "Favourite programming language?",
"choices": [
"Swift",
"Python",
"Objective-C",
"Ruby"
]
}
+ Response 201 (application/json)
+ Headers
Location: /questions/2
+ Body
{
"question": "Favourite programming language?",
"published_at": "2015-08-05T08:40:51.620Z",
"choices": [
{
"choice": "Swift",
"votes": 0
}, {
"choice": "Python",
"votes": 0
}, {
"choice": "Objective-C",
"votes": 0
}, {
"choice": "Ruby",
"votes": 0
}
]
}
Patch
## User [/users/{id}]
### Update a User [POST]
+ Request (application/json)
{
"id": 1,
"fname": "Pandurang",
"lname": "Patil",
"email": "[email protected]"
}
+ Response 200 (application/json)
{
"id": 1,
"fname": "Pandurang",
"lname": "Patil",
"email": "[email protected]"
}
+ Response 401 (application/json)
{
"error": "error.unauthorized"
}