restful,一个好的RESTfulAPI，具备特征
restful,一个好的RESTfulAPI，具备特征详细介绍
本文目录一览： restful是什么意思
restful在中文中有"使人感到悠闲的、宁静的"的意思，restful是什么意思 restful的中文翻译、读音、例句，其次还有"平静的"的意思，在线读音是[r'estful]，restful是一个英语形容词。
restful的中文翻译
1.使人感到悠闲的
例句:Distributed applications using HTTP as an application protocol, and built RESTfully, do have a contract, but of a different nature and kind.
翻译:用HTTP作为应用协议、以RESTful方式构建的分布式应用其实有一个契约，但其性质和种类却不相同。
2.宁静的
例句:i find cemeteries very... restful places, don't you?
翻译:我觉得墓园... 是个非常宁静的地方，不是吗？
3.平静的
例句:# The restful peace within #
翻译:你内心无声的和平。
什么是 restful？
RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商作为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。
RESTful架构是对MVC架构改进后所形成的一种架构，通过使用事先定义好的接口与不同的服务联系起来。在RESTful架构中，浏览器使用POST，DELETE，PUT和GET四种请求方式分别对指定的URL资源进行增删改查操作。因此，RESTful是通过URI实现对资源的管理及访问，具有扩展性强、结构清晰的特点。
RESTful架构将服务器分成前端服务器和后端服务器两部分，前端服务器为用户提供无模型的视图；后端服务器为前端服务器提供接口。浏览器向前端服务器请求视图，通过视图中包含的AJAX函数发起接口请求获取模型。
项目开发引入RESTful架构，利于团队并行开发。在RESTful架构中，将多数HTTP请求转移到前端服务器上，降低服务器的负荷，使视图获取后端模型失败也能呈现。但RESTful架构却不适用于所有的项目，当项目比较小时无需使用RESTful架构，项目变得更加复杂。
REST和RESTFUL
REST（Representational State Transfer）,表述性状态转移，定义了互联网架构原则，是一种架构风格，具体原则如下：
1.互联网所有资源都可以被抽象为资源
2.每个资源都有唯一的资源标识符
3.同一个资源具有多个表现形式（可以是json,xml等等）
4.对资源的操作不会改变资源标识符
5.所有的操作都是无状态的
主要是就是说互联网上的资源可以用一种规则来表示，对资源的操作是无状态的。
RESTFUL,是指遵守rest规则的web服务，restful是一种ROA(Resource Oriented Architecture，面向资源的架构)，restful的核心概念就是资源（Resource）。
互联网中客户端和服务端的交互就是资源的表述，这种表述是无状态的，也就意味着服务端要报错资源的所有状态，客户端可以通过http协议按照规定的规则访问或者改变资源的状态，就是所谓的“表述性状态转移”。
具体表现形式如下：
GET /users 获取用户列表
GET /users/1 获取id（主键）为1的用户
POST /users 创建用户
PUT /users/1 修改id为1的用户（整条数据替换）
PATCH /users/1 修改id为1的用户（数据局部字段替换）
DELETE /users/1 删除id为1的用户
简单来说就是通过请求方法名来表示行为，url来表示操作的资源
更多例子：
GET /users/1/products 获取id为1用户下的产品列表
GET /users/1/products/1 获取id为1用户下的id为1的产品
GET /users/name/aaa/products 获取name为aaa的用户下的产品列表
GET /users/name/aaa/products/name/ppp 获取name为aaa的用户下的名为ppp的产品
POST /users/1/products id为1的用户下创建一个产品
PUT /users/1/products/1 修改id为1的用户下的id为1的产品（整条数据替换）
PATCH /users/1/products/1 修改id为1的用户下的id为1的产品（数据局部字段替换）
DELETE /users/1/products/1 修改id为1的用户下的id为1的产品
什么是RESTfulAPI
什么是RESTfulAPI？RESTfulAPI是什么，以及如何使用它？RESTfulAPI是一种建立在HTTP协议和标准Web技术之上的API设计风格。它允许客户端和服务器之间进行交互，并利用现有的通信协议传输数据。与SOAP等其他传输协议相比，RESTfulAPI具有更好的可伸缩性和可维护性。要了解RESTfulAPI，必须先理解以下三个概念：1.资源：指的是可通过API访问的任何内容，例如网站上的文章、图像、评论等。对于每个资源，应该确定它的唯一标识符，以便轻松地与其交互。2.HTTP方法：指的是客户端可用于访问资源的方式，常用的方法有GET、POST、PUT和DELETE。3.表示：指的是服务器返回资源的表现形式，可以是HTML、XML、JSON或其他格式。RESTfulAPI的核心思想是通过HTTP方法以及URI对资源进行增删改查操作。例如：1.GET方法：用于获取资源，如从服务器检索网站上的文章或图像。示例URI：/articles/123。2.POST方法：用于创建新资源，如在网站上发布新文章或评论。示例URI：/articles。3.PUT方法：用于更新现有资源，例如更新文章的标题或内容。示例URI：/articles/123。4.DELETE方法：用于删除资源，例如删除文章或评论。示例URI：/articles/123。在实现RESTfulAPI时，应遵循以下几个原则：1.状态应该保存在客户端，而不是服务器上。2.必须使用标准HTTP方法和状态代码3.返回的表示应该是可缓存的。4.URI应该唯一标识每个资源。5.与服务器端无状态通信，每次请求都应该包括所有必要的信息。正确定义和实现RESTfulAPI，可以帮助开发人员更好地构建可扩展的分布式应用程序。此外，RESTfulAPI还可以被用于构建web服务，使其更加安全和高效。
Restful协议
Representational State Transfer, 是一种软件架构风格，提供一系列限制指导，用于更好的创建 web service 。 符合REST 架构风格的web service 称为Restful web service。
其核心是以 资源 为关注点，而不是方法或消息, RESTful通常是用URL定位资源，HTTP动词（GET, POST, DELETE, PUT等) 描述对资源的操作，该操作过程即改变资源的表现形式，可使用JSON, XML等文件传递该资源操作信息。
Web端主要负责渲染和附带处理简单的商务逻辑，通过Restful API (JSON或其他格式，动词 + 名词)来传递数据和改变数据状态
简要对比下RPC & REST & SOA，不同的服务器向客户端提供服务的方法
SOAP和REST严格来说不是两个对等的概念，可理解为两种服务设计思想和及其具体的实现架构。
二者各有自己的使用场景。如果创建的分布式服务要求较好的安全性，对于传输等底层实现要求较强的可定制性，可以考虑SOAP；如果要求设计实现简单，一般来说安全性要求不高可以考虑REST。这只是一般情况，但偏于面向资源的服务使用REST有天然的优势。
SOAP在.NET中多使用WCF框架，而RESTful则多使用Web API。 具体可参考 Microsoft技术杂志文章
Restful 的好处，无需关注不同的Client等
一个好的RESTfulAPI，具备特征
一个好的RESTfulAPI，应该具备以下特征：
这个API应该是对浏览器友好的，能够很好地融入Web，而不是与Web格格不入。
1.浏览器是最常见和最通用的REST客户端。好的RESTfulAPI应该能够使用浏览器HTML完成所有的测试（不需要使用编程语言）。这样的API还可以很方便地使用各种自动化的Web功能测试、性能测试工具来做测试。Web前端应用（基于浏览器的RIA应用、移动App等等）也可以很方便地将多个RESTfulAPI的功能组合起来，建造Mashup类的应用。
这个API中所包含的资源和对于资源的操作，应该是直观和容易理解的，并且符合HTTP协议的要求。
REST开发又被称作“面向资源的开发”，这说明对于资源的抽象，是设计RESTfulAPI的核心内容。RESTfulAPI建模的过程与面向对象建模类似，是以名词为核心的。这些名词就是资源，任何可命名的抽象概念都可以定义为一个资源。而HTTP协议并不是一种传输协议，它实际提供了一个操作资源的统一接口。对于资源的任何操作，都应该映射到HTTP的几个有限的方法（常用的有GET/POST/PUT/DELETE四个方法，还有不常用的PATCH/HEAD/OPTIONS方法）上面。所以RESTfulAPI建模的过程，可以看作是具有统一接口约束的面向对象建模过程。
按照HTTP协议的规定，GET方法是安全且幂等的，POST方法是既不安全也不幂等的（可以用来作为所有写操作的通配方法），PUT、DELETE方法都是不安全但幂等的。将对资源的操作合理映射到这四个方法上面，既不过度使用某个方法（例如过度使用GET方法或POST方法），也不添加过多的操作以至于HTTP的四个方法不够用。
2.如果发现资源上的操作过多，以至于HTTP的方法不够用，应该考虑设计出更多的资源。设计出更多资源（以及相应的URI）对于RESTfulAPI来说并没有什么害处。
这个API应该是松耦合的。
RESTfulAPI的设计包括了三个循序渐进、由低到高的层次：资源抽象、统一接口、超文本驱动。正是这三个层次确保了RESTfulAPI的松耦合性。
3.当设计面向互联网的API时，松耦合变成了一种“必须有”的强需求。紧耦合的API非常脆弱，一旦公布出去，服务器端和客户端都无法持续进化。尤其是服务器端，公布出去的接口根本不敢改，改了之后，几乎所有客户端应用立即无法正常工作。REST这种架构风格就是紧耦合API的解毒剂，这个话题可以谈的很深，这里就不展开了。感兴趣的读者可以参考《REST实战》。
这个API中所使用的表述格式应该是常见的通用格式
在RESTfulAPI中，对于资源的操作，是通过在服务器端-客户端之间传递资源的表述来间接完成的。资源的表述可以有很多种格式，并且在响应和请求中的资源表述格式也会有所不同。GET/POST响应中的资源表述格式，常见的有HTML、XML、JSON；POST/PUT请求中的资源表述格式，常见的有标准的HTML表单参数、XML、JSON。
4.这些常见表述格式，处理起来非常容易，有大量的框架和库提供支持。所以除非有很合理的要求，通常不需要使用自定义的私有格式。
使用HTTP响应状态代码来表达各种出错情况
HTTP响应状态代码，是HTTP协议这个统一接口中用来表达出错情况的标准机制。响应状态代码分成两部分：statuscode和reasonphase。两部分都是可定制的，也可以使用标准的statuscode，只定制reasonphase。
5.如果一个所谓的“RESTfulAPI”对于任何请求都返回200OK响应，在响应的消息体中返回出错情况信息，这种做法显然不符合“确保操作语义的可见性”这个REST架构风格的基本要求。
这个API应该对于HTTP缓存是友好的
6.充分利用好HTTP缓存是RESTfulAPI可伸缩性的根本。HTTP协议是一个分层的架构，从两端的useragent到originserver之间，可以插入很多中间组件。而在整个HTTP通信链条的很多位置，都可以设置缓存。HTTP协议内建有很好的缓存机制，可以分成过期模型和验证模型两套缓存机制。如果API设计者完全没有考虑过如何利用HTTP缓存，那么这个API的可伸缩性会有很多问题。
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、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。
关于RESTful的六个限制
RESTfulapi是开发中常用的概念，那什么是REST，什么又是RESTfulapi？
REST是Representational State Transfer的缩写 Representational :数据的表现形式(JSON、XML...) State:当前状态或者数据 Transfer：数据传输 看字面意思还是不太懂，没关系，接着看： 标准的 REST 六个限制如下：
参考内容：客户端-服务器模型
参考内容：无状态协议
参考内容：网页缓存
统一接口约束是设计任何REST服务的基础。
参考内容：分层系统
参考内容：客户端脚本
上文中提到了REST的6个限制，其中统一的接口需要统一成什么样子的呢？ 1.资源的标识
RESTfulapi就是符合REST风格的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）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
Restful接口文档规范
基于目前的大前端时代，对于常年负责后台开发的我来说， 最重要的就是提供稳定的接口和文档。便于小伙伴们进行业务对接。
当下常用的是RestFul风格的定义规范， 之前开发是清一色Get、Post。引入RestFul后感觉接口定义规范很多，看接口地址就知晓是什么功能， 一起来看看列的一些基础规范吧。
API与客户端用户的通信协议，总是使用HTTPS协议，以确保交互数据的传输安全。
应该尽量将API部署在专用域名之下： https://api.example.com
如果确定API很简单,不会有进一步扩展,可以考虑放在主域名下： https://www.example.com/api
https://api.example.com/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://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees
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=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】、数据类型、是否必填、中文描述。
相应参数：类型、中文描述。