Alan Tsai 的學習筆記


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

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

2019-03-26 Tuesday
[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
台灣 Pay QR Code
台灣 Pay QR Code
Line Pay 一卡通 QR Code
Line Pay 一卡通 QR Code
街口支付QR Code
支付寶QR Code
街口支付QR Code
微信支付QR Code
2019-03-26 Tuesday
comments powered by Disqus