restful接口规范,restful 接口规范

restful api接口规范是什么？

REST（REpresentationStateTransfer）描述了一个架构样式的网络系统，比如web应用程序。

一般依赖于HTTP认证，HTTP认证有几种：basic，digest，token，这些都有标准的实现的开源包需要主要的是这个认证的帐号跟你业务的帐户实际是不一样的。REST属于webService一种，安全是后台服务的安全，因此不需要实际的业务帐号，通常是系统keyStore证书库里的账户。

RESTFUL特点包括：

1、每一个URI代表1种资源。

2、客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

3、通过操作资源的表现形式来操作资源。

4、资源的表现形式是XML或者HTML。

5、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。

REST接口规范

资源URL设计原则

REST风格规定所有资源通过统一资源定位符（URL）定位，资源的RESTful URL采用以下模板：

http(s)://ip:port/(rest)/{service-name}/{version}/{rest-convention}

一个完整URL由服务接口入口、服务接口标识（rest）、服务名称{service-name}、版本号{version}、服务内资源路径{rest-convention}组成，其中服务接口标识"/rest"非规范强制要求

如：获取所有角色基本信息

【规则】若服务接口归属于固定域名，ip:port应该由域名替代。

【规则】URL中字段命名采用英文半角小写字母、数字、中划线或下划线组合，如"search-by-group"，不建议采用驼峰式命名。

【规则】URL长度应小于2083字符，否则服务端返回414状态码

【规则】URL中不能包含URL特殊字符（RFC1738标准），特殊字符需使用特殊字符时需要做URL encode。

【规则】URL中不得包含公司安全红线涉及的敏感信息。

【建议】website暴露给WebUI的RESTful采用模板：

http(s)://ip:port/(rest)/{website-name}/ui/{version}/{rest-convention}

说明：为保持系统对外接口风格一致，在{website-name}和{version}之间添加"ui"标识当前接口为website对外提供的接口。

什么是RESTful

先看REST是什么意思，英文Representational state transfer 表述性状态转移 其实就是对 资源 的表述性状态转移。

简单的说：RESTful是一种架构的规范与约束、原则，符合这种规范的架构就是RESTful架构。

资源的地址 在web中就是URL （统一资源标识符）

资源是REST系统的核心概念。 所有的设计都是以资源为中心

结合项目怎么识别资源

1.商品加入购物车 购物车

2.提交订单 订单

3.创建用户 用户

围绕资源进行 添加，获取，修改，删除，以及对符合特定条件的资源进行列表操作 。针对资源设计接口

RESTful 架构的核心规范与约束：统一接口

分为四个子约束：

1.每个资源都拥有一个资源标识，每个资源的资源标识可以用来唯一地标明该资源

2.消息的自描述性

3.资源的自描述性。

4.HATEOAS Hypermedia As The Engine Of Application State(超媒体作为应用状态引擎)

即客户只可以通过服务端所返回各结果中所包含的信息来得到下一步操作所需要的信息，如到底是向哪个URL发送请求等。也就是说，一个典型的REST服务不需要额外的文档标示通过哪些URL访问特定类型的资源，而是通过服务端返回的响应来标示到底能在该资源上执行什么样的操作

目的：实现客户端无需借助任何文档即能调用到所有的服务器资源

三、资源的URL设计

1.通过URL来表示资源

资源分为主资源与子资源

因为主资源是一类独立的资源 所以主资源应直接放在相对路径下：例如

若要表示主资源的实例：如果实例的ID=1，则这样表示： /goods/1

子资源：

一个实例的子资源可能是一个集合也可能是一个单一的子资源

子资源为图片集合：/goods/1/pictures

子资源为商品折扣的单子子资源：/goods/1/discount

2.单数 vs. 复数

获取用户1的信息，哪种方式更符合RESTful?

/api/users/1

/api/user/1

3.相对路径 vs. 请求参数

极光的RESTful API:

获取用户信息 GET /v1/users/{username} 参数放在路径中

VS

获取用户信息 GET /v1/users?username=xxxxx 拼接的方式

获取应用管理员列表 GET /v1/admins?start={start}count={count} ？后拼接参数的方式：这种方式一般作为过滤资源

4.使用合适的动词 get delete put post

选择请求接口的方式： get delete

PUT 在服务器更新资源（客户端提供改变后的完整资源）。

POST 在服务器新建一个资源

5.使用标准的状态码

GET

hello world!!!

多终端 为什么采用restful的接口设计规范

REST（REpresentationStateTransfer）描述了一个架构样式的网络系统，比如web应用程序。

它首次出现在2000年RoyFielding的博士论文中，他是HTTP规范的主要编写者之一。

REST指的是一组架构约束条件和原则。

满足这些约束条件和原则的应用程序或设计就是RESTful。

Web应用程序最重要的REST原则是，客户端和服务器之间的交互在请求之间是无状态的。

从客户端到服务器的每个请求都必须包含理解请求所必需的信息。

如果服务器在请求之间的任何时间点重启，客户端不会得到通知。

此外，无状态请求可以由任何可用服务器回答，这十分适合云计算之类的环境。

客户端可以缓存数据以改进性能。

在服务器端，应用程序状态和功能可以分为各种资源。

资源是一个有趣的概念实体，它向客户端公开。

资源的例子有：应用程序对象、数据库记录、算法等等。

每个资源都使用URI（UniversalResourceIdentifier）得到一个惟一的地址。

所有资源都共享统一的界面，以便在客户端和服务器之间传输状态。

使用的是标准的HTTP方法，比如GET、PUT、POST和DELETE。

Hypermedia是应用程序状态的引擎，资源表示通过超链接互联。

另一个重要的REST原则是分层系统，这表示组件无法了解它与之交互的中间层以外的组件。

通过将系统知识限制在单个层，可以限制整个系统的复杂性，促进了底层的独立性。

当REST架构的约束条件作为一个整体应用时，将生成一个可以扩展到大量客户端的应用程序。

它还降低了客户端和服务器之间的交互延迟。

统一界面简化了整个系统架构，改进了子系统之间交互的可见性。

REST简化了客户端和服务器的实现。

RESTful的实现：RESTfulWeb服务与RPC样式的Web服务了解了什么是什么是REST，再看看RESTful的实现。

最近，使用RPC样式架构构建的基于SOAP的Web服务成为实现SOA最常用的方法。

RPC样式的Web服务客户端将一个装满数据的信封（包括方法和参数信息）通过HTTP发送到服务器。

Restful接口文档规范

基于目前的大前端时代，对于常年负责后台开发的我来说， 最重要的就是提供稳定的接口和文档。便于小伙伴们进行业务对接。

当下常用的是RestFul风格的定义规范， 之前开发是清一色Get、Post。引入RestFul后感觉接口定义规范很多，看接口地址就知晓是什么功能， 一起来看看列的一些基础规范吧。

API与客户端用户的通信协议，总是使用HTTPS协议，以确保交互数据的传输安全。

应该尽量将API部署在专用域名之下：

如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下：

{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中的名词也应该使用复数。

例子:

GET（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=1pageSize=20 指定第几页，以及每页的记录数。

/v1/products?sortBy=nameorder=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】、数据类型、是否必填、中文描述。

相应参数：类型、中文描述。