前後端標準 API Spec 定義

[iamcxa]

API 基本定義

• 以 model 為單位，各自有自己的 CRUD API
• 後台 API 以 /api/admin 為標準前綴

Response 通用規範

成功訊息

{
    "success": true,
    "status": 200,
    "message": "successed",
    "data": {
    },
}

失敗訊息

• 單筆錯誤

{
    "success": false,
    "status": 400,
    "message": "Error.User.Name.Required",
    "data": {}
}

• 多筆錯誤

{
    "success": false,
    "status": 400,
    "data": {},
    "errors": [{
        "message": "Error.User.Email.Wrong.Format",
    }]
}
```

[iamcxa]

---

[get] - list 取得清單

• request 格式

api/{modelName}/{int}
  ?perPage={int}
  &curPage={int}
  &sort={string}
  &search={string}

• response 格式

{
  // 搜尋條件
  "filter": {
    // 篩選特定欄位
    "fields": [{
      "key": "", // table column name
      "value": "", // search value
    }],
    // 全文檢索
    "keyword": "" 
  },
  // Result Object
  "items": [{
    id: 1,
    username: "q12312"
  }],
  // 分頁
  "paging": {
    "total": 50,
    "lastPage": 15,
    "perPage": 15,
    "curPage": 1,
    "sort": "DESC",
  }
}

---

[post] - create 新增一筆資料

以 user 為例

• request 格式

  • URL : api/{modelName}

    api/user
    

  • Payload

    {
      nickName: 'john',
      email: '[email protected]',
    }
    

• response 格式

{
    id: 1,
    nickName: 'john',
    email: '[email protected]',
}

---

[put] - update 更新一筆資料

以 user 為例

• request 格式

  • URL : api/{modelName}/{id}

    api/user/1
    

  • Payload

    {
      nickName: 'john1',
    }
    

• response 格式

{
    id: 1,
    nickName: 'john1',
    email: '[email protected]',
}

---

{delete} - destroy 刪除一筆資料

以 user 為例

• request 格式 : api/{modelName}/{id}

api/user/1