RESTFul API 接口文档模板

最新推荐文章于 2024-07-29 11:40:36 发布

坏习惯的叛逆者

最新推荐文章于 2024-07-29 11:40:36 发布

阅读量5w

点赞数 16

分类专栏：基础文章标签： HTTP REST API

本文链接：https://blog.csdn.net/wenxueliu/article/details/86422121

版权

基础专栏收录该内容

5 篇文章 0 订阅

订阅专栏

修订记录

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

说明

排版约定

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

编码

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

时间与日期

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

表示日期一律采用YYYY-MM-DD方式，例如2016-06-01表示2016年6月1日
表示时间一律采用hh:mm:ss方式，并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
凡涉及日期和时间合并表示时，在两者中间加大写字母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 任务提交成功。

返回值	说明
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 任务异常错误信息编码。

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

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

响应样例

正常响应：

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

异常响应：

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

批量接口

正常响应要素说明

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

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

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