Skip to content

API

RealWorld

Microsoft

Paypal

Twitter

Discord

文件

格式

7 Open-Source OpenAPI Documentation Generators

版本進版的時機和注意事項

以使用API的使用者去思考, 盡量朝向使用者不須異動的狀況 若需異動, 要通知

a breaking change is any change that requires a third-party developer to do any migration work to maintain the existing functionality of their application

A "breaking change" is any change that requires the consumer of an API to make lockstep changes in order for the consuming code to continue to work properly.

向前相容 Breaking change and Non-breaking change Breaking change => 修改欄位名稱, 刪除欄位, 修改欄位資料格式(e.g. from an integer to a float), 回傳格式異動(e.g. from XML to JSON)

分析

response

payload, response code

單一欄位資料異動 新增欄位: 原本沒有"abc", 新增一個"abc" 刪除欄位: 原本存在"def", 移除"def" 修改欄位名稱: 原本欄位名稱"abc", 修改為"abcd" 修改欄位型態: 原本"abc"為int=>123, 修改為string=>"123"

<svg version="1.1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 402 349" width="402" height="349">
  <!-- svg-source:excalidraw -->

  <defs>
    <style>
      @font-face {
        font-family: "Virgil";
        src: url("https://excalidraw.com/Virgil.woff2");
      }
      @font-face {
        font-family: "Cascadia";
        src: url("https://excalidraw.com/Cascadia.woff2");
      }
    </style>
  </defs>
  <rect x="0" y="0" width="402" height="349" fill="#ffffff"></rect>
<g stroke-linecap="round" transform="translate(95 221) rotate(0 73 59)">
    <path d="M1.4 -1.79 C54.57 -0.19, 106.15 -1.34, 145.95 -1.15 M0.68 0.06 C32.45 -0.56, 65.36 0.12, 146.77 -0.18 M145.86 -0.7 C145.76 27.89, 143.26 57.34, 146.84 118.54 M146.11 0.32 C145.45 38.98, 146.87 76.13, 145.49 117.87 M146.8 117.78 C102.59 116.75, 61.17 118.05, -1.78 119.11 M145.86 117.45 C113.5 117.97, 79.81 119.76, -0.7 118.49 M-1 118.8 C-0.97 90.75, 1.08 61.28, 1.97 -0.6 M0.91 118.68 C-0.09 75.88, 1.02 36.41, -0.98 0.92" stroke="#000000" stroke-width="1" fill="none"></path></g><g transform="translate(10 10) rotate(0 39 26)"><text x="0" y="19" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#000000" text-anchor="start" style="white-space: pre;" direction="ltr">before:</text><text x="0" y="45" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#000000" text-anchor="start" style="white-space: pre;" direction="ltr">no "abc"</text></g><g transform="translate(274 14) rotate(0 59 26)"><text x="0" y="19" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#000000" text-anchor="start" style="white-space: pre;" direction="ltr">after:</text><text x="0" y="45" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#000000" text-anchor="start" style="white-space: pre;" direction="ltr">"abc": "hello"</text></g><g stroke-linecap="round"><g transform="translate(146 217) rotate(0 -39.812045040465875 -77.26465291405096)"><path d="M-0.87 -0.65 C-14.24 -26.86, -66.61 -130.15, -79.71 -156.15 M0.88 1.62 C-12.67 -23.88, -67.04 -128.48, -80.5 -154.7" stroke="#000000" stroke-width="1" fill="none"></path></g><g transform="translate(146 217) rotate(0 -39.812045040465875 -77.26465291405096)"><path d="M-59.52 -133.89 C-66.46 -140.58, -74.86 -148.19, -78.61 -152.95 M-58.59 -134.17 C-65.02 -139.88, -70.03 -145.5, -79.78 -155.12" stroke="#000000" stroke-width="1" fill="none"></path></g><g transform="translate(146 217) rotate(0 -39.812045040465875 -77.26465291405096)"><path d="M-77.75 -124.46 C-78.51 -134.25, -80.65 -145.11, -78.61 -152.95 M-76.82 -124.74 C-78.61 -132.79, -78.89 -140.85, -79.78 -155.12" stroke="#000000" stroke-width="1" fill="none"></path></g></g><g stroke-linecap="round"><g transform="translate(201 216) rotate(0 38.89635766426102 -74.91328799687327)"><path d="M0.51 1.13 C13.48 -24.2, 65.28 -125.96, 78.48 -150.96 M-0.69 0.68 C12.03 -24.01, 63.93 -124.71, 77.26 -149.92" stroke="#000000" stroke-width="1" fill="none"></path></g><g transform="translate(201 216) rotate(0 38.89635766426102 -74.91328799687327)"><path d="M75.22 -121.05 C72.86 -129.54, 77.75 -141.41, 78.54 -151.75 M74.11 -119.36 C75.16 -129.47, 76.11 -138.2, 78.03 -149.23" stroke="#000000" stroke-width="1" fill="none"></path></g><g transform="translate(201 216) rotate(0 38.89635766426102 -74.91328799687327)"><path d="M57.02 -130.53 C61.15 -135.76, 72.43 -144.29, 78.54 -151.75 M55.91 -128.84 C62.33 -135.97, 68.71 -141.87, 78.03 -149.23" stroke="#000000" stroke-width="1" fill="none"></path></g></g><g transform="translate(100 267) rotate(0 68 13.5)"><text x="68" y="19" font-family="Virgil, Segoe UI Emoji" font-size="20px" fill="#000000" text-anchor="middle" style="white-space: pre;" direction="ltr">Client/User</text></g>
</svg>

結構異動 {"abc": ["first", "half"]} {"abc": [{"first": 1}, {"half": 9}]}

格式異動 json => xml

request

payload

新增必填欄位: 原本沒有"abc", 新增一個必填"abc"

Auth

參考OAuth 2.0 Client Credentials Flow 實作 - https://auth0.com/docs/get-started/authentication-and-authorization-flow/call-your-api-using-the-client-credentials-flow - https://developer.twitter.com/en/docs/authentication/oauth-2-0/application-only - https://www.jetbrains.com/help/space/client-credentials.html#response

Rate limit

回傳值

Error code pattern for API

combination of top-level HTTP status codes and lower level API error codes - HTTP is a ==ubiquitous== protocol and is no doubt understood by your web container.

input - syntax - 不能攜帶危險物品 - schema - 不能攜帶危險物品 - value - 不能攜帶危險物品 - exist - The resource of the URL doesn't exist. - 某些物品根本不存在於活動會場

auth - caller's credentials were invalid - 不能進入活動場地 - caller's credentials were valid, but their access level isn't sufficient to access the resource - 可以進入活動場地, 但不能使用或瀏覽某些物品

活動場地本身 - Something bad happened inside the server itself, this error could be anything. - 天花板壞掉或展示櫃毀損 - An error occurred when calling downstream service - 和保全公司或清潔公司的人員失聯, 無法執行保全或清潔服務 - A useful response code for when you get hammered with a ton of "happy" customers who are inadvertently DDOS'ing your service. - 入場人數已達場地容量限制, 再多會造成活動品質下降 - a timeout instead of an actual error with the downstream service - 保全公司或清潔公司可以聯絡, 但他們剛好在忙別的事情, 無法在時限內趕到事發現場

資料更新