1. 编程号首页

RESTFul API 接口文档模板

编程小号 • • 未分类

RESTFul API 接口文档模板修订记录发布日期修改说明2019-01-01第一次发布说明排版约定排版格式含义<>变量[]可选项{}必选项|互斥关系等宽字体CourierNew屏幕输出编码若请求消息体中的参数支持中文，则中文字符必须为UTF-8编码。时间与日期日期与时间的表示有多种方式。为统一起见，除非是约定俗…

修订记录

发布日期 修改说明
2019-01-01 第一次发布

说明

排版约定

排版格式 含义
< > 变量
[ ] 可选项
{ } 必选项
| 互斥关系
等宽字体Courier New 屏幕输出

编码

若请求消息体中的参数支持中文，则中文字符必须为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 协议的标准头域不再这里列出了。

消息头（Header） 是否必须 说明
Content-Type 可选 application/json; charset=utf-8

公共响应消息头

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

消息头（Header） 说明
Content-Type 只支持JSON格式，application/json; charset=utf-8

错误返回格式

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

参数名 类型 说明
code string 错误码
message string 错误描述
body string 本次请求的体

示例

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

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

公共错误码

错误码 错误描述 HTTP 状态码 中文解释 英文解释

错误码

参考各接口错误码。

接口说明

接口简介

依次列出所有接口

类型 子类型 说明

接口调用流程

说明接口使用流程

XXXX

描述

对接口的描述

URI

POST /v1/{id}/user

Path 参数

参数 说明

query 参数

参数 是否必须 描述

请求消息头

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

参数 说明 是否必须 示例

请求参数体

参数名称 类型 描述 是否必须
result xxx 对取值范围，约束，说明，示例的描述 是

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

xxx 字段数据结构说明

参数 类型 描述 是否必选

返回消息头

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

或

参数 说明 是否必须 示例

返回参数

参数名称 类型 描述
subnets List xxx 子网列表

xxx 字段数据结构说明

参数 是否必选 参数说明 描述

错误码

HTTP 状态码 错误码 错误描述 中文解释 英文解释 建议措施

请求示例

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 网关超时。
状态码 编码 状态说明
100 Continue 继续请求。这个临时响应用来通知客户端，它的部分请求已经被服务器接收，且仍未被拒绝。
101 Switching Protocols 切换协议。只能切换到更高级的协议。例如，切换到HTTP的新版本协议。
201 Created 创建类的请求完全成功。
202 Accepted 已经接受请求，但未处理完成。
203 Non-Authoritative Information 非授权信息，请求成功。
204 NoContent 请求完全成功，同时HTTP响应不包含响应体。在响应OPTIONS方法的HTTP请求时返回此状态码。
205 Reset Content 重置内容，服务器处理成功。
206 Partial Content 服务器成功处理了部分GET请求。
300 Multiple Choices 多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择。
301 Moved Permanently 永久移动，请求的资源已被永久的移动到新的URI，返回信息会包括新的URI。
302 Found 资源被临时移动。
303 See Other 查看其它地址。使用GET和POST请求查看。
304 Not Modified 所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。
305 Use Proxy 所请求的资源必须通过代理访问。
306 Unused 已经被废弃的HTTP状态码。
400 BadRequest 非法请求。建议直接修改该请求，不要重试该请求。
401 Unauthorized 在客户端提供认证信息后，返回该状态码，表明服务端指出客户端所提供的认证信息不正确或非法。
402 Payment Required 保留请求。
403 Forbidden 请求被拒绝访问。返回该状态码，表明请求能够到达服务端，且服务端能够理解用户请求，但是拒绝做更多的事情，因为该请求被设置为拒绝访问，建议直接修改该请求，不要重试该请求。
404 NotFound 所请求的资源不存在。建议直接修改该请求，不要重试该请求。
405 MethodNotAllowed 请求中带有该资源不支持的方法。建议直接修改该请求，不要重试该请求。
406 Not Acceptable 服务器无法根据客户端请求的内容特性完成请求。
407 Proxy Authentication Required 请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权。
408 Request Time-out 服务器等候请求时发生超时。客户端可以随时再次提交该请求而无需进行任何更改。
409 Conflict 服务器在完成请求时发生冲突。返回该状态码，表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成。
410 Gone 客户端请求的资源已经不存在。返回该状态码，表明请求的资源已被永久删除。
411 Length Required 服务器无法处理客户端发送的不带Content-Length的请求信息。
412 Precondition Failed 未满足前提条件，服务器未满足请求者在请求中设置的其中一个前提条件。
413 Request Entity Too Large 由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息。
414 Request-URI Too Large 请求的URI过长（URI通常为网址），服务器无法处理。
415 Unsupported Media Type 服务器无法处理请求附带的媒体格式。
416 Requested range not satisfiable 客户端请求的范围无效。
417 Expectation Failed 服务器无法满足Expect的请求头信息。
422 UnprocessableEntity 请求格式正确，但是由于含有语义错误，无法响应。
429 TooManyRequests 表明请求超出了客户端访问频率的限制或者服务端接收到多于它能处理的请求。建议客户端读取相应的Retry-After首部，然后等待该首部指出的时间后再重试。
500 InternalServerError 表明服务端能被请求访问到，但是不能理解用户的请求。
501 Not Implemented 服务器不支持请求的功能，无法完成请求。
502 Bad Gateway 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。
503 ServiceUnavailable 被请求的服务无效。建议直接修改该请求，不要重试该请求。
504 ServerTimeout 请求在给定的时间内无法完成。客户端仅在为请求指定超时（Timeout）参数时会得到该响应。
505 HTTP Version not supported 服务器不支持请求的HTTP协议的版本，无法完成处理。

任务类接口

  • 正常响应要素说明

    名称 参数类型 说明
    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" 
                 }
              ]
}

今天的文章RESTFul API 接口文档模板分享到此就结束了，感谢您的阅读。

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 举报，一经查实，本站将立刻删除。
如需转载请保留出处：https://bianchenghao.cn/6041.html

赞 (0)
编程小号编程小号
0

相关推荐

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注