Alan Tsai 的學習筆記


學而不思則罔,思而不學則殆,不思不學則“網貸” 記錄軟體開發的點點滴滴 著重於微軟技術、網頁開發、DevOps、C#, Asp .net Mvc、Azure、AI、Chatbot、Docker、Data Science

[apiary][03]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - API Blueprint基本結構介紹篇

2019-03-26 星期二
[apiary][03]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - API Blueprint基本結構介紹篇.jpg
圖片來源:https://pixabay.com/en/books-spine-colors-pastel-1099067/,logl來源:https://apiary.io/

在上一篇 ([apiary][02]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - 工具使用介紹篇) 瞭解了怎麽使用apiary這一個工具來撰寫api的文件之後。

在這一篇將來實際的撰寫看看感覺如何。

之前提到過apiary預設的文件格式是API Blueprint,因此這一篇將來看看API Blueprint怎麽使用,並且看看撰寫起來感覺如何。

定一個Scenario

在往下介紹之前,先來想象某一個情景。

假設今天要建立一個功能是一個很簡單的TODO app,在初期只需要簡單的 Create、Read、Update以及Delete (CRUD) 就可以。

那麽怎麽設計這個API呢?

API Blueprint的基本結構

首先,API Blueprint就是markdown加上一些變形,因此只要會markdown,非常容易上手 (如果是Markdown苦手,這篇最後面有放一個鏈接到一個markdown的cheat sheet可以參考)。

不太確定是哪一個版本的markdown,有支援table,但是又沒有支援ToDo List,因此可能是變形版本的GitHub Flavored Markdown。

整個 API Blueprint 拆解下來大概有這麽幾個關鍵的部分:

  1. Metadata - 主要定義那個版本的API Blueprint
  2. API Name 和 Description - API的名稱以及説明
  3. Resource Group - 相關的Resource可能放在同一個group裡面
  4. Resource - 和某個資源有觀的API
  5. Actions - 實際可以被觸發執行的内容

來細部看看每一個部分代表什麽。

Metadata

每一個API Blueprint的最一開始就是metada,主要有兩個值:

  1. FORMAT - 定義使用那個版本的API Blueprint,大部分都是1A
  2. HOST - 定義正式機器的base網址 - 用來驗證後端api是否正確用

常見的設定可能如下:

FORMAT: 1A
HOST: http://polls.apiblueprint.org/

API Name 和 Description

在 Metadata下面以一個# 為開始的就是 API Name

API Name下面的文字就是Description。

Description 可以用任意markdown的語法 - 包含不同的subheading或者是table

範例:

# TODO 功能API

這是一個 TODO 功能 API的描述文件

## 這是第二段落

可以用Table

|  a |  b |   c|  d | e  |
|---|---|---|---|---|
|  1 | 2  |  3 |  4 |  5 |

最後呈現會是:

chrome_2019-03-26_20-33-25.png
呈現内容

Resource Group

如果説有好多個Resource相關,可以把他們Group在一起。

主要差異是在Document呈現那邊,同一個group的會在同一個下面。

Resource Group的使用方式是,用heading符號(#) 然後後面跟著關鍵字 Group

例如:

# Group 功能1

以下為功能1相關的服務

在Documentation看起來選單就會多一層:

chrome_2019-03-26_20-49-16.png
可以看到多一層結構 - 當resource很多的時候方便切割

如果沒有設定任何Resource Group,那麽大家都是在同一個預設的Resource Group裡面。

Resource

Resource簡單來説就是某一個api網址,例如我的TODO的CRUD可能是同一個 Resource (網址),只是不同的 Action (http verb)

Resource一般是兩個#,加上一段説明文字,後面一個方框帶入route。

例如:

## Todo API [/api/todo]

Actions

Action就是實際動作發生的地方 - 簡單來説如果以RESTFul的角度來看,那麽就是對應到http verb。

Action一般是三個#,加上一段説明文字,後面一個方框帶入http verb。也可以帶入route訊息 (如果和Resource的route不一樣的話)

例如:

### 取得所有的ToDo [GET]

如果說要調整route,舉例來説取得單筆的時候:

### 取得單筆TODO [GET /api/todo/{todoId}]
Actions這邊還有很多細節,例如URI Template,或者怎麽定義傳入的參數以及回傳回來的格式等等。這些下一篇介紹。

這一篇的完整API Blueprint整個内容如下:

FORMAT: 1A
HOST: http://polls.apiblueprint.org/

# TODO 功能API

這是一個 TODO 功能 API的描述文件

## 這是第二段落

可以用Table

|  a |  b |   c|  d | e  |
|---|---|---|---|---|
|  1 | 2  |  3 |  4 |  5 |

# Group 功能1

以下為功能1相關的服務

## Todo API [/api/todo]

### 取得所有的ToDo [GET]

### 取得單筆TODO [GET /api/todo/{todoId}]

取得單筆todo資料

結語

這篇介紹完了API Blueprint的幾個主要架構項目,不過漏掉了怎麽定義Actions的部分。

由於Actions是文件的核心,也牽扯到request以及response的内容,因此這個部分將會在下一篇介紹。

在下一篇([apiary][04]設計API時好用的工具 - 讓前後端溝通格式不再卡卡 - API Blueprint Actions格式篇),將會針對Actions裡面的定義做介紹,包含了怎麽定義網址的參數,定義傳入的内容以及得到的結果格式等。

參考資料

API Blueprint官方tutorial
這邊有完整的spec以及tutorial可以參考:https://apiblueprint.org/documentation/tutorial.html
Github的Mastering Markdown
如果Markdown不熟悉,那麽可以參考github整理的一個小抄:https://guides.github.com/features/mastering-markdown/

如果文章對您有幫助,就請我喝杯飲料吧
街口支付QR Code
街口支付QR Code
街口支付QR Code
支付寶QR Code
街口支付QR Code
微信支付QR Code
2019-03-26 星期二
comments powered by Disqus