restful api接口规范 (restful API)
本文目录导航：
restful api接口规范
restful api接口规范如下：
1、协定
API与用户的通讯协定，总是经常使用HTTPs协定。
2、域名
应该尽量将API部署在公用域名之下。
假设确定API很繁难，不会有进一步裁减，可以思考放在主域名下。
3、版本（Versioning）
应该将API的版本号放入URL。
另一种做法是，将版本号放在HTTP头消息中，但不如放入URL繁难和直观。
Github驳回这种做法。
4、门路（Endpoint）
门路又称终点（endpoint），示意API的详细网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。
普通来说，数据库中的表都是同种记载的汇合（collection），所以API中的名词也应该经常使用双数。
举例来说，有一个API提供生物园（zoo）的消息，还包括各种生物和雇员的消息，则它的门路应该设计成上方这样。
openapi接口规范
OpenAPI接口规范又称为RESTfulAPI接口规范，是一种现代的Web服务接口规范，用于形容从软件客户端到服务端之间的接口调用行为。
OpenAPI接口规范可以让Web 服务更容易了解，从而更容易被开发者经常使用，从而更快捷地成功接口开发。
OpenAPI是一种服务接口规范，用于形容丛客户端到服务端之间的接口调用行为。
OpenAPI自身就是一种谨严的接口规范,它使得Web服务调用更容易了解、更容易保养，也更容易被客户端经常使用。
OpenAPI由一组资源组成，每个资源向客户端泄露了一些接口配置，经过资源及其行为(即接口配置)，客户端就可以调用Web 服务，从而成功特定的配置。
OpenAPI使得客户端和服务端之间的接口调用更容易了解和成功，也裁减了Web 服务的定义、构建和部署的才干。
总之，OpenAPI接口规范是一种十分弱小的Web 服务接口规范，它可以有效和繁难地成功Web 服务的开发、部署和调用。
OpenAPI接口规范不只可以更容易地成功接口开发,还允许多种可裁减的API定义，可以更好地满足客户端的需求。
OpenAPI的运行曾经宽泛，在Web服务开发中，OpenAPI 接口规范是必无法少的，它可以协助开发者更快更有效地成功接口开发，让开发愈加高效。
Restful接口文档规范
基于目前的大前端时代，关于终年担任后盾开发的我来说， 最关键的就是提供稳固的接口和文档。
便于小同伴们启动业务对接。
当下罕用的是RestFul格调的定义规范， 之前开发是清一色Get、Post。
引入RestFul后觉得接口定义规范很多，看接口地址就通晓是什么配置， 一同来看看列的一些基础规范吧。
API与客户端用户的通讯协定，总是经常使用HTTPS协定，以确保交互数据的传输安保。
应该尽量将API部署在公用域名之下：假设确定API很繁难,不会有进一步裁减,可以思考放在主域名下：https:///v {n} 1、应该将API的版本号放入URL。
2、驳回多版本并存，增量颁布的模式。
3、n代表版本号，分为整型和浮点型 整型： 大配置版本， 如v1、v2、v3 ... 浮点型： 补充配置版本， 如v1.1、v1.2、v2.1、v2.2 ... 4、关于一个 API 或服务，应在消费中最多保管 3 个最详细的版本 门路又称终点（end point），示意API的详细网址。
1、在RESTful架构中，每个网址代表一种资源(resource),所以网址中不能有动词，只能有名词。
【所用的名词往往与数据库的表格名对应】 2、数据库中的表普通都是同种记载的汇合(collection),所以API中的名词也应该经常使用双数。
例子:https:///v1/usersGET（SELECT）： 从主机取出资源（一项或多项）。
POST（CREATE）： 在主机新建一个资源。
PUT（UPDATE）： 在主机降级资源（客户端提供扭转后的完整资源）。
DELETE（DELETE）： 从主机删除资源。
例子： GET /v1/products 失掉一切商品 GET /v1/products/ID 失掉某个指定商品的消息 POST /v1/products 新建一个商品 PUT /v1/products/ID 降级某个指定商品的消息 DELETE /v1/products/ID 删除某个商品,更正当的设计详见【9、非RESTful API的需求】 GET /v1/products/ID/purchases 列出某个指定商品的一切投资者 GET /v1/products/ID/purchases/ID 失掉某个指定商品的指定投资者消息 若记载数量很多，主机无法能前往所有记载给用户。
API应该提供分页参数及其它挑选参数，过滤前往结果。
/v1/products?page=1&pageSize=20 指定第几页，以及每页的记载数。
/v1/products?sortBy=name&order=asc 指定前往结果依照哪个属性排序，以及排序顺序。
传入参数分为4种类型： 1、cookie： 普通用于OAuth认证 2、request header： 普通用于OAuth认证 3、恳求body数据： 4、地址栏参数： 1）restful 地址栏参数 /v1/products/ID ID为产品编号，失掉产品编号为ID的消息 2）get模式的查问字段 见【六、过滤消息】 response： ---------------------------------------- { status: 200, // 详见【status】 data: { code: 1, // 详见【code】 data: {} || [], // 数据 message: 成功, // 寄存照应消息揭示,显示给客户端用户【须语义化中文揭示】 sysMessage: success // 寄存照应消息揭示,调试经常使用,中英文都行 ... // 其它参数，如 total【总记载数】等 }, msg: 成功, // 寄存照应消息揭示,显示给客户端用户【须语义化中文揭示】 sysMsg: success // 寄存照应消息揭示,调试经常使用,中英文都行 } ---------------------------------------- 【status】: 200: OK 400: Bad Request 500：Internal Server Error 401：Unauthorized 403：Forbidden 404：Not Found 【code】: 1: 失掉数据成功 | 操作成功 0：失掉数据失败 | 操作失败 1、实践业务展开环节中，或者会产生各种的api不是繁难的restful 规范能成功的。
2、须要有一些api打破restful规范准则。
3、特意是移动互联网的api设计，更须要有一些特定的api来提升数据恳求的交互。
1)、删除单个 | 批量删除 ： DELETE /v1/product body参数{ids：[]} 2)、页面级API : 把以后页面中须要用到的一切数据经过一个接口一次性性前往所有数据 1、前端须要哪些字段，API接口应该前往哪些字段，字段不多也不少。
2、降级配置尽量做到：首次前往的原始数据参数与提交降级的数据参数结构分歧。
3、期间参数，尽量以分歧格局的字符串传递， 如： ‘2019-01’ | ‘2019/01’ ‘2019-01-01’ | ‘2019/01/01’ ‘2019-01-01 12:12:12’ | ‘2019/01/01 12:12:12’ 1、尽量驳回智能化接口文档，可以做到在线测试，同步降级。
2、应蕴含：接口BASE地址、接口版本、接口模块分类等。
3、每个接口应蕴含： 接口地址：不蕴含接口BASE地址。
恳求模式: get、post、put、delete等。
恳求参数：数据格局【自动JSON、可选form data】、数据类型、能否必填、中文形容。
相应参数：类型、中文形容。
phper