文件化你的REST API (fork from https://gist.github.com/iros/3426278)

api.md

標題

<有關你的API呼叫的附加資訊。試著使用符合要求(request)類型(獲取 vs 更動)與多數(單數vs複數)的動詞.>

• URL

  <URL的結構(只需要用路徑，不需要root url)>

• Method(方法):

  <要求的類型>

  GET | POST | DELETE | PUT

• URL Params(URL參數)

  <如果存在URL params，指出它們在URL區段的提到的名稱。將可選的(optional)與必要的(required)分開來。將資料限制文件化記下。>

  Required(必要):

  id=[integer]

  Optional(可選):

  photo_id=[alphanumeric]

• Data Params(資料參數)

  <如果是要進行POST要求，body的有效資料會是長什麼樣子？ URL參數規則也可以套用在這裡>

• Success Response(成功回應):

  <當成功時應該要有什麼狀態碼回傳，和有無回傳資料？這當使用者需要知道它們的回應是不是如預期時，會相當有幫助！>

  • Code(狀態碼): 200
    Content(內容): { id : 12 }

• Error Response(錯誤回應):

  <大部份的端點將會有許多會造成失敗的方式。從沒有認証的存取，到不正確的參數等等。它們應該都要全部列在這裡。這會看起來很單調重複的，但它可以幫助避免產生錯誤回應的假定發生位置。>

  • Code(狀態碼): 401 UNAUTHORIZED
    Content(內容): { error : "Log in" }

  或

  • Code(狀態碼): 422 UNPROCESSABLE ENTRY
    Content(狀態碼): { error : "Email Invalid" }

• 呼叫範例:

  <填上呼叫到你的端點的可以執行格式的範例 (例如 $.ajax 呼叫或 curl 要求) - 這可以讓生活更輕松與更可被預測。>

• 註解:

  <這裡可以寫下所有不確定的、評論、討論結果等等。我會建議當留下評論時，加上時間戳記和可識別是誰留下的。.>

example.md

呈現會員資料

回傳單一會員的json資料

• URL

  /users/:id

• Method:

  GET

• URL Params

  Required:

  id=[integer]

• Data Params

  無

• Success Response:

  • Code: 200
    Content: { id : 12, name : "陸小鳳" }

• Error Response:

  • Code: 404 NOT FOUND
    Content: { error : "會員不存在" }

  或

  • Code: 401 UNAUTHORIZED
    Content: { error : "你沒有能進行這個要求的授權" }

• 呼叫範例:

    axios.get("/users/1")
    .then((res) => { console.table(res.data) })
    .catch((error) => { console.error(error) })
    .finally(() => { /* 不論失敗成功皆會執行 */ })