restful接口规范

API 设计规范

• 所有的路径都是资源，例如：/users、/messages
• 所有操作使用 http method 表示
  • post => 创建
  • get => 获取
  • put => 更新
  • delete => 删除

• 路径中不存在 action，错误示例： /users/:userId/update

  常用示例

  GET method

  读取资源，从服务端返回相应资源。

  • GET /apps（获取所有应用）
  • GET /apps/:appId（获取指定应用）
  • GET /users/:userId/apps（获取指定用户的所有应用）
  • GET /apps?userId=255223（获取指定用户的所有应用）
  • GET /orders?page=2&per_page=100（每页100个订单，返回第2页的100个订单）
  • GET /orders?limit=25&offset=50（从第50个开始，返回25个订单）

POST method

创建资源，创建成功后，返回创建的资源。

• POST /apps（创建应用）

  // HTTP Request Body
  {
    "name": "appName",
    "pkg": "http://fds.api.com/bucket/app.pkg"
  }

• POST /users/:userId/apps（创建指定用户下的应用）

  // HTTP Request Body
  {
    "name": "appName",
    "pkg": "http://fds.api.com/bucket/app.apk"
  }

PATCH method

部分更新：提供资源的部分数据进行更新，更新成功后，返回更新后的资源。

• PATCH /apps/:appId（更新应用名称）

  // HTTP Request Body
  {
    "name": "appName",
  }

• PATCH /messages（批量更新消息为已读）

  // HTTP Request Body
  [
    {
      "id": "88231",
      "readed": true,
    },
    {
      "id": "88232",
      "readed": true,
    }  
  ]

PUT method

整体更新：提供全部数据，进行覆盖式更新；如果相应 ID 的数据不存在，可以进行创建；更新成功后，返回更新的资源。

• PUT /apps/:appId（整体更新应用）

  // HTTP Request Body 提供应用的所有数据
  {
    "name": "appName",
    "pkg": "http://fds.api.com/bucket/app.pkg"
  }

• PUT /apps（批量更新应用）

  // HTTP Request Body
  [
    {
      "id": "8823",
      "name": "appName",
      "pkg": "http://fds.api.com/bucket/app.pkg"
    },
    {
      "id": "8229",
      "name": "alipay",
      "pkg": "http://fds.api.com/bucket/app.pkg"
    }  
  ]

DELETE method

删除资源，从服务端删除相应资源，并返回删除的资源。

• DELETE /apps/:appId（删除指定应用）
• DELETE /apps?ids=8823,8824（批量删除应用 ）
• DELETE /apps?userId=252262707&ids=8823（删除指定用户的指定应用）
• DELETE /users/:userId/apps?ids=8823（删除指定用户的指定应用）

响应规则

请求响应状态码，一共5种，分别是请求成功、客服端错误、服务端错误、认证失败、权限错误。

为什么分为这五种，请求成功自成一类就不说了。响应错误分为客户端错误以及服务端错误两大类，这是为了后期更方便地进行维护，快速定位问题出在前端还是后端。而将认证失败和权限错误单独抽出来是因为这两种错误出现频繁且前端相应的处理逻辑比较特殊。

• 请求成功

  • HTTP Status Code 200

  • HTTP Response Body

    {
      "data": {
        // All data should be here.
      }
    }

• 客服端错误

  • HTTP Status Code 400

  • HTTP Response Body

    {
      "error": {
        // 该 code 标识错误的唯一性，浏览器端可以根据该 code 做 UI 层的展现
        "code": 4411,
        "message": "Name should start by a letter."   
      }
    }

• 服务端错误

  • HTTP Status Code 500

  • HTTP Response Body

    {
      "error": {
        // 该 code 标识错误的唯一性，浏览器端可以根据该 code 做 UI 层的展现
        "code": 5502,
        "message": "Server is unavailable."   
      }
    }

• 认证错误

  • HTTP Status Code 401

  • HTTP Response Body

    {
      "error": {
        // 该 code 标识错误的唯一性，浏览器端可以根据该 code 做 UI 层的展现
        "code": 4401,
        "message": "Your token has expired."   
      }
    }

• 权限错误

  • HTTP Status Code 403

  • HTTP Response Body

    {
      "error": {
        // 该 code 标识错误的唯一性，浏览器端可以根据该 code 做 UI 层的展现
        "code": 4403,
        "message": "You have no right to delete user."
      }
    }