RESTFul API 接口文档模板

大家好，欢迎来到IT知识分享网。

修订记录

说明

排版约定

编码

若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。

时间与日期

日期与时间的表示有多种方式。为统一起见，除非是约定俗成或者有相应规范的，凡需要日期时间表示的地方一律采用UTC时间，遵循ISO 8601，并做以下约束：

1. 表示日期一律采用YYYY-MM-DD方式，例如2016-06-01表示2016年6月1日
2. 表示时间一律采用hh:mm:ss方式，并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
3. 凡涉及日期和时间合并表示时，在两者中间加大写字母T，例如2016-06-01T23:00:10Z表示UTC时间2016年6月1日23点0分10秒

发送请求

共有三种方式可以基于已构建好的请求消息发起请求，分别为：

• cURL

  cURL是一个命令行工具，用来执行各种URL操作和信息传输。cURL充当的是HTTP客户端，可以发送HTTP请求给服务端，并接收响应消息。cURL适用于接口调试。关于cURL详细信息请参见https://curl.haxx.se/。

• 编码

  通过编码调用接口，组装请求消息，并发送处理请求消息。

• REST客户端

  Mozilla、Google都为REST提供了图形化的浏览器插件，发送处理请求消息。针对Firefox，请参见FirefoxREST Client；针对Chrome，请参见Postman。

API 规格

公共请求消息头

下表列出了所有 XXX API 所携带的公共头域。HTTP 协议的标准头域不再这里列出了。

公共响应消息头

下表列出了所有 XXX API的公共响应头域。HTTP协议的标准响应头域不再这里列出了。

错误返回格式

XXX 错误响应符合BCE规范，统一为如下格式。后续各接口不再单独列出。

示例

{ 
   
    "code" : "AccessDenied",
    "message" : "Access denied.",
    "body" : ""
}

其中，code为错误码，所有错误码取值来源 XXX 公共错误码和 XXX 专有错误码。

公共错误码

错误码

参考各接口错误码。

接口说明

接口简介

依次列出所有接口

接口调用流程

说明接口使用流程

XXXX

描述

对接口的描述

URI

POST /v1/{id}/user

Path 参数

query 参数

请求消息头

除公共消息头外，无其它特殊消息头。

请求参数体

注：类型部分，如果是一个对象，可以在用 xxx 字段数据结构 在下面表格说明

xxx 字段数据结构说明

返回消息头

除公共消息头，无其它特殊消息头。

或

返回参数

xxx 字段数据结构说明

错误码

请求示例

URI

Header

Body

应答示例

Status

Header

Body

参考

华为公有云 API 接口

https://support.huaweicloud.com/api-ecs/zh-cn_topic_0065792793.html

https://support.huaweicloud.com/api-ecs/zh-cn_topic_0020805967.html

https://support.huaweicloud.com/api-cci/cci_02_3002.html

附录

通用请求返回值

• 正常

  返回值	说明
  200	请求成功。
  202	任务提交成功，当前系统繁忙，下发的任务会延迟处理。
  204	任务提交成功。

• 异常

  返回值	说明
  300 multiple choices	被请求的资源存在多个可供选择的响应。
  400 Bad Request	服务器未能处理请求。
  401 Unauthorized	被请求的页面需要用户名和密码。
  403 Forbidden	对被请求页面的访问被禁止。
  404 Not Found	服务器无法找到被请求的页面。
  405 Method Not Allowed	请求中指定的方法不被允许。
  406 Not Acceptable	服务器生成的响应无法被客户端所接受。
  407 Proxy Authentication Required	用户必须首先使用代理服务器进行验证，这样请求才会被处理。
  408 Request Timeout	请求超出了服务器的等待时间。
  409 Conflict	由于冲突，请求无法被完成。
  500 Internal Server Error	请求未完成。服务异常。
  501 Not Implemented	请求未完成。服务器不支持所请求的功能。
  502 Bad Gateway	请求未完成。服务器从上游服务器收到一个无效的响应。
  503 Service Unavailable	请求未完成。系统暂时异常。
  504 Gateway Timeout	网关超时。

任务类接口

• 正常响应要素说明

  名称	参数类型	说明
  job_id	String	提交任务成功后返回的任务ID，用户可以使用该ID对任务执行情况进行查询。如何根据job_id来查询Job的执行状态，请参考查询Job状态。

• 异常响应要素说明

  名称	参数类型	说明
  error	字典数据结构	提交任务异常是返回的异常信息，详情请参见 error 数据结构说明。

  error 数据结构说明

  名称	参数类型	说明
  message	String	任务异常错误信息描述。
  code	String	任务异常错误信息编码。

• 响应样例

  正常响应：

  { 
        
      "job_id": "70a599e0-31e7-49b7-b260-868f441e862b", 
  } 
  

  异常响应：

  { 
        
      "error": { 
       "message": "", "code": XXX}
  } 
  

批量接口

• 正常响应要素说明

  名称	参数类型	说明
  response	列表数据结构	提交请求成功后返回的响应列表，详情请参见下面response数据结构说明。

  response数据结构说明

  名称	参数类型	说明
  id	String	操作成功的虚拟机id

• 异常响应要素说明

  名称	参数类型	说明
  error	字典数据结构	批量请求异常时返回的整体异常信息，详情请参见 error 数据结构。
  internalError	列表数据结构	批量请求处理中，每一个单个请求的具体异常信息，详情请参见 internalError 数据结构说明。

  error 数据结构说明

  名称	参数类型	说明
  message	String	批量操作整体异常错误信息描述。
  code	String	批量操作整体异常错误信息编码。

  internalError 数据结构说明

  名称	参数类型	说明
  id	String	具体单个请求操作失败的虚拟机id
  error_message	String	具体单个请求操作失败的错误信息描述。
  error_code	String	具体单个请求操作失败的错误信息编码。

• 响应样例

  正常响应：

  { 
        
      "response": [
                    { 
       
                      "id": "616fb98f-46ca-475e-917e-2563e5a8cd19"   
                    },
                    { 
       
                      "id": "516fb98f-46ca-475e-917e-2563e5a8cd12"   
                    }
                 ]
  }
  

  异常响应：

  { 
       
       "error": { 
       
                   "code": "Ecs.xxxx",
                   "message": "xxxxxxxxxxxxxxx" 
                 },
       "internalError": [
                   { 
       
                      "id": "616fb98f-46ca-475e-917e-2563e5a8cd19",
                      "error_code": "ECS.XXXX",
                      "error_message": "xxxxxxxxxxxxxxx" 
                    },
                   { 
       
                       "id": "516fb98f-46ca-475e-917e-2563e5a8cd12",
                       "error_code": "ECS.XXXX",
                       "error_message": "xxxxxxxxxxxxxxx" 
                   }
                ]
  }