时序图与 API 呼叫流程

时序图 (Sequence Diagram, Timeline Diagram)，是 UML 底下的一种图表，这种时序图最常看见用在解释 API 的执行工作顺序，还有向第三方专业的厂商做技术串接时，对方可能需要提供我方呼叫情境图，这样的图就派上用场了。

时序图的绘画很像鬼脚图，只不过鬼脚图遇到节点就要转弯，对时序图来说，每个人都是独立时间点的呼叫与处理，也可以用来形容同时进行的工作 (Multi-Thread, Coroutine)。

在这里的呼叫，是指任何呼叫形式有 "一来一回" 的做法，举例像是 HTTP Request 就是很经典的有一个 Request 就有一个 Response。

比方说下图是一个 ATM 的情境，从使用者开始，每个节点都有他们分别要做的事情，蓝色的区块就是时间轴，从 1 执行到 ATM 时，ATM 再向其他系统调用资料。

图中的 b-a 特别纪录了使用者这段收到回传的时间小於 10 sec，可以告知这段执行期间大概需要花多久。

假设我们有一个电商系统，与其他物流商、金流平台、发票平台都谈好 API 如何实作，各自就开出了 API (为了应景，写了简易的 API Spec):

金流平台

从我方平台向金流平台建立付款的 API。

POST | /v1/payment/create_payment
Body:

{
    "api_key": xxxxxx,
    "merchant_id": xxxxx,
    "payment_item": [ … ],
    "amount": xxxx,
    "payment_notify_hook_url": "请提供您的 webhook url",
    "customer_paid_redirect": "请提供您给使用者交易完成後跳转",
    "hash_iv": xxxx
}

Response:

{
    "status": "ok",
    "payment_token": xxxxxxxxxxxxxx,
    "payment_url_with_token": "https://xxxxx.xxxxx?token=xxxxxxxx"
}

第一个: 用於接收金流付款成功资讯的我方 API Router

POST /[自订 Router Path]
接收从金流端来的 API:

{
    "payment_token": xxxxxxxxxxxxxxxxxx,
     "status": 1,
    ….etc
}

请在收到 API 後回传以下讯息:

{
   "status": 1 // if ok
}

通常这样的 API 都会要求要做白名单加强安全性:
Whitelist: 100.xxx.xxx.xxx, ….etc

物流商

向物流商平台建立一个物流编号用於订单。

POST | /generate_logistic_sn
Body:

{
    "merchant_id": xxxx,
    "merchant_token_id": xxxx
}

Response:
HTTP 200

{
    "logistic_sn":xxxxxxxxxxxxxxxxxx,
    "tracking_url": "https://xxxx..x.xx?sn=xxxxxxxx"
}

财政部

向财政部请求建立发票。

POST Multipart File | /create_invoices
Multipart: xls, csv, xlsx
Header:
Authorization: Bearer xxxxxxxxxxxxxxxx
Body:

{
    "merchant_id": xxxx,
}

大家各自都开完了所有的 API 给电商平台串接，在付款的金流串接上，方法是先把使用者的订单建立好，丢给金流平台先开启交易，然後把 token 带给使用者，让使用者跳转去金流平台交易 (即 1.1 ~ 1.3)。

使用者自己交易完成後使用者就会根据电商平台之前建立付款的 redirect url 给使用者一个 "感谢您的购买页面"，金流平台会用 Web Hook 的方式把使用者付款资讯，在背後回传给电商平台，所以电商平台自己要提共 Web Hook 来接受付款成功通知 (注意 2.2 回传没有使用虚线箭头)。

电商平台接收到付款成功通知，就去开一张财政部发票，同时寄送 Email 给使用者 (注意这块回传 2.6 没有使用虚线箭头)，再去建立物流商 API ，然後另外再通知一次给使用者说要等待寄件 (2.9 也没有虚线)。

实线箭头跟虚线箭头，在下面这张图代表的是 Request (Message 请求) 及 Response (Replay Message, 回传)，会产生回传，在这张图的假设就是需要有人提出请求，才会有 Reply 回传，比方说像是 Web Hook，就是金流平台主动 Request 电商平台告知讯息，然後在 2.3 电商必须回传给金流平台他是否收到正常，此时回应的虚线箭头就是从 B2C 到金流平台。

如果都是需要 Coding 的部门在做跨部门沟通的时候，可以使用时序图来作画，可以轻易让对方了解各自领域系统的执行方式。

上述 API 都塞在文件中不太美观，顺带一提，在跨部门沟通的 API Schema 标准上，可以采用公制承认的规范，像是 Open API Spec，然後将 API 使用 Swagger 工具 (或是 Postman 开出来) 呈现给对方，可以从文件去测试你的规格。

References:
[1] https://circle.visual-paradigm.com/category/uml-diagrams/sequence-diagram/
[2] http://dita-ot.sourceforge.net/1.5.3/dev_ref/DITA-OTGenListModule.html
[3] https://docs.sessionm.com/workflows/APIWorkflowTimeline.pdf