前言

API

API 是程序给程序呼叫的接口，可以是应用程序、资料、装置之间的接口，比如：

• 新闻 app 的开发人员串接公司内的 API，来取得新闻列表、文章内容等资讯。
• 写一个及时翻译 app 需要呼叫 Google 翻译的 API 来取得翻译结果。
• 写一个音乐 app 并将控制逻辑写成 API，开放给其他智慧音箱的厂商串接控制。

为什麽要写这篇

我们的确很少需要设计 API，顶多是公司内部参与讨论，
但除了离线使用、工具型的 app，
基本上我们都要接 API 来交换及时的、个人化的资料，
所以接下来就强调在应用的部分。

RESTful API

RESTful API 是专指 HTTP 协定下的一种设计方式，
一般 app 的资料都是透过 RESTful API 来跟自己公司的服务器交换资料，
动作则是分为 CRUD（新增、查询、修改、删除）。
例如：

{} 内的东西表示变数，domain 是网域，如：https://www.google.com

• 新增文章：POST {domain}/article
• 取得文章：GET {domain}/article/{article id}
• 修改文章：PUT {domain}/article/{article id}
• 删除文章：DELETE {domain}/article/{article id}

POST、PUT 所上传的文章内容会放在 HTTP request 的 body 里面，
GET 所得到的文章内容会放在 HTTP response 的 body 里面，
而不管是 POST 上 server 或是 GET 下 client，目前主流都是 JSON 格式。

应用

手动打 API

有些情境下，我们需要自己手动打 API：

• 我们不知道是 API 的问题还是自己程序的问题，可以手动打 API 测试，避免一直 build code，浪费时间。
• 我们想要很快完成很难走到的流程，如：已经完成新增文章功能，却还没有实作删除文章功能，就可以手动打删除 API。

那要怎麽手动打呢？
在 desktop 中，可以用 Postman，几个重点功能：

• 分类。
• 云端备份。
• 切换 domain（公司经常有分内/外部 API 环境）。
• ...

在 Android 上也有类似软件，如：Rest Client，临时需要了解状况也可以应急。

从 API 拿到的 JSON 很丑

在 Android Studio 中就有 plugin 可以美化。

观察网页的 API

图片中的范例使用 chrome、edge，按下 F12 并切换到 network 的页签，
有时候可以从这里得到一些有用的资讯。

API 文件

比较常见的制作工具如：

• aglio
• Swagger

虽然我们不用制作 API 文件，
但可以先参考 范例，进公司後才不会慌。

结语

其实公司内部的 API 制定也不是跟我们无关，我们提出这些问题不一定只是利己，可能也是在帮助 server side 做维护。

像是：

• 以前同一个意义的栏位名称词性、时态、单复数等等，都会造成栏位无法共用。
• 其他 API 都有同一个 JSON object，但这次少了某个栏位，但在之前的情况都不能为空，那也会造成需要多一个 class 来装资料的情况。