跳至主要内容

試著讓初學者理解 API

基本解釋​

API（Application Programming Interface），中文翻為應用程式介面，用一句話來解釋的話，就是：兩個應用程式（電腦）接觸時所要依照的規範。

以面交買東西為例，假如今天我要跟別人面交買東西，那我們一定會事先約好：

  1. 要在哪裡碰面。
  2. 我要給他什麼（例如錢、以及身分證件）。
  3. 他會給我什麼。

假設我想要在我的電腦，跟別人的電腦拿資料，那我們會事先約定好「在哪裡碰面」、「我要給他什麼」、「他會給我什麼」。 那角色對調過來，如果是別人的電腦要跟我拿資料，那我也會跟他約定好「在哪裡碰面」、「我要他給我什麼」、「我會給他什麼」。

如果我的電腦很熱門，那我可能就會直接把這三項規定公開給大家。想要跟我拿資料的就自己按照我的規定：在哪裡找到我、你要給我什麼，這樣我就會給你東西。 這個「規定」就叫做 API。

用程式的名詞來幫這三個東西命名，就叫做：URL, Request, Response。 URL 就是網址，代表如果你要跟我拿資料，那就輸入這個網址。 Request 字面翻譯就是「要求」，我要求你給我哪些東西。 Response 字面翻譯就是「回應」，代表我最後會給你這些東西。

API 的用法​

我們直接拿 Axios 來說明，這個是工程師常用到的免費開源 API 服務。 Axios 常用的用法有：GET, POST, PUT。 我先把角色分清楚：GET, POST, PUT 是以要拿資料的電腦的角度出發，而 URL, Request, Response 則是從要給資料的電腦的角度出發。

GET​

以在 Facebook 貼文為例。 如果今天我要看某個人的某篇文章，於是我點進了這個文章頁面。這時 Facebook 的前端工程師就要跟後端去拿資料，既然是「拿」資料，通常就會用 GET。 而後端所列出的 API 可能長這樣：

URL: 127.0.0.1/post
Request: post_id, post_user_id, user_id
Response: time, content, likes, comments

假設他們的資料庫放在 127.0.0.1 這個電腦，那後端可能就會跟前端說，

  • 我的資料放在 127.0.0.1/post 這個網址。
  • 你要給我的東西是：你想要看哪篇貼文（post_id）、發文的人是誰（post_user_id）、想要看這篇貼文的是誰（user_id）。如果發文的人跟使用者不是好友，可能就會被擋住。
  • 我會回傳給你：發文時間（time）、文章內容（content）、有誰按讚（likes）、留言有哪些（comments）。 （這邊要說明，在 Axios 的 GET 用法中，其實是沒有 Request 的，這些東西通常會被塞在 URL 裡面，例如 127.0.0.1/post/post_id=123&post_user_id=456&user_id=789。不過這邊為了方便說明，就還是先這樣寫。）

POST​

假設今天是使用者要發文，通常會用 POST。後端列出的 API 可能長這樣：

URL: 127.0.0.1/post
Request: user_id, content, time
Response: "發文成功"

雖然這邊的網址跟 GET 一樣，但是因為一個是 GET，一個是 POST。用法不同，所以可以同時存在，不會衝突。

  • 我的資料放在 127.0.0.1/post 這個網址，但這個例子比較像是：我要在這個網址跟你拿資料。
  • 你要給我發文的人是誰（user_id）、發文內容（content）、發文時間（time）。
  • 我會回傳給你：「發文成功」（message）。

PUT​

假設今天使用者要編輯貼文，通常會用 PUT。後端列出的 API 可能長這樣：

URL: 127.0.0.1/post
Request: user_id, content, time
Response: "發文成功"
  • 我的資料放在 127.0.0.1/post 這個網址，但這個例子比較像是：我要在這個網址跟你拿資料。
  • 你要給我發文的人是誰（user_id）、發文內容（content）、發文時間（time）。
  • 我會回傳給你：「發文成功」（message）。 這個例子來說，PUT, POST 的 API 其實蠻像的。但這只是剛好這個例子是這樣而已。