resful协议1

1、重要概念：

RESTFul API已是如今互联网里对外开放接口的主流模式，可参考：git

豆瓣API https://developers.douban.com/wiki/?title=api_v2github

GitHub https://developer.github.com/v3/数据库

分享关于resful协议：json

https://www.jianshu.com/p/294fcc945db7api

https://blog.igevin.info/posts/restful-api-get-started-to-write/数组

1. resful协议简介

1 RESTful架构风格最初由Roy T. Fielding（HTTP/1.1协议专家组负责人）在其2000年的博士学位论文中提出。HTTP就是该架构风格的一个典型应用。从其诞生之日开始，它就因其可扩展性和简单性受到愈来愈多的架构师和开发者们的青睐。一方面，随着云计算和移动计算的兴起，许多企业愿意在互联网上共享本身的数据、功能；另外一方面，在企业中，RESTful API（也称RESTful Web服务）也逐渐超越SOAP成为实现SOA的重要手段之一。时至今日，RESTful架构风格已成为企业级服务的标配。 2 
3 REST即Representational State Transfer的缩写，可译为"表现层状态转化”。REST最大的几个特色为：资源、统一接口、URI和无状态。
4 
5 restful是一种架构风格，其核心是面向资源

resful协议简介

首先restful是一种软件架构风格或者说是一种设计风格，并非标准，它只是提供了一组设计原则和约束条件，主要用于客户端和服务器交互类的软件。缓存

 1 resful的六个限制(约束)和这些约束的优势：  2 
 3 1.客户-服务器（Client-Server）客户端服务器分离  4 优势，提升用户界面的便携性（操做简单）  5 经过简化服务器提升可伸缩性（高性能，低成本）  6 容许组件分别优化（可让服务端和客户端分别进行改进和优化）  7 
 8 2.无状态（Stateless）  9 从客户端的每一个请求要包含服务器所须要的全部信息 10 优势： 11 提升可见性（能够单独考虑每一个请求） 12 提升了可靠性（更容易从局部故障中修复） 13 提升可扩展性（下降了服务器资源使用） 14 
15 3.缓存（Cachable） 16 服务器返回信息必须被标记是否能够缓存，若是缓存，客户端可能会重用以前的信息发送请求。 17 优势： 18 减小交互次数 19 减小交互的平均延迟 20 
21 4.分层系统（Layered System） 22 系统组件不须要知道与他交流组件以外的事情。封装服务，引入中间层。 23 优势： 24 限制了系统的复杂性 25 提升可扩展性 26 
27 5.统一接口（Uniform Interface） 28 优势： 29 提升交互的可见性 30 鼓励单独改善组件 31 
32 6.支持按需代码（Code-On-Demand 可选） 33 优势： 34 提升可扩展性

resful的六个限制(约束)和这些约束的优势：

二、resful的10大设计规范

总结一下什么是RESTful架构：安全

（1）每个URI表明一种资源；服务器

（2）客户端和服务器之间，传递这种资源的某种表现层；restful

（3）客户端经过四个HTTP动词，对服务器端资源进行操做，实现"表现层状态转化"。

一、路径（接口命名）

在RESTful架构中，每一个网址表明一种资源（resource），因此在url接口中尽可能要使用名词，不要使用动词，并且所用的名词每每与数据库的表格名对应。

通常来讲，数据库中的表都是同种记录的"集合"（collection），因此API中的名词也尽可能使用复数。

二、动做

能够根据Http不一样的method，进行不一样的资源操做（5种方法：GET / POST / PUT / DELETE / PATCH）

1 GET （SELECT）：从服务器检索特定资源，或资源列表。 2 POST （CREATE）：在服务器上建立一个新的资源。 3 PUT （UPDATE）：更新服务器上的资源，提供整个资源。 4 PATCH （UPDATE）：更新服务器上的资源，仅提供更改的属性。 5 DELETE （DELETE）：从服务器删除资源。

五种方法

三、版本控制

版本控制：API必定要有版本号。不必定要在URL路径在，能够再hearder加也能够在 url参数加。不过我认为放到路径好一些。如：http://api.example.com/v1.0/foo

四、过滤信息（Filtering）

若是记录数量不少，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

1 ?limit=10：指定返回记录的数量 2 ?offset=10：指定返回记录的开始位置。 3 ?page_number=2&page_size=100：指定第几页，以及每页的记录数。 4 ?sortby=name&order=asc：指定返回结果按照哪一个属性排序，以及排序顺序。 5 ?animal_type_id=1：指定筛选条件 6 参数的设计容许存在冗余，即容许API路径和URL参数偶尔有重复。好比， 7 GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

常见参数

五、url中能够体现这是个API接口

https://www.example.com/api/

六、状态码（Status Codes）

获得的响应应该包含状态码：

1 1xx 信息，请求收到，继续处理。范围保留用于底层HTTP的东西，你极可能永远也用不到。 2 2xx 成功，行为被成功地接受、理解和采纳 3 3xx 重定向，为了完成请求，必须进一步执行的动做 4 4xx 客户端错误，请求包含语法错误或者请求没法实现。范围保留用于响应客户端作出的错误，例如。他们提供不良数据或要求不存在的东西。这些请求应该是幂等的，而不是更改服务器的状态。 5 5xx 范围的状态码是保留给服务器端错误用的。这些错误经常是从底层的函数抛出来的，甚至 6 开发人员也一般无法处理，发送这类状态码的目的以确保客户端得到某种响应。 7 当收到5xx响应时，客户端不可能知道服务器的状态，因此这类状态码是要尽量的避免。

状态码种类

 1 服务器向用户返回的状态码和提示信息，常见的有如下一些（方括号中是该状态码对应的HTTP动词）。  2 
 3 200 OK - [GET]：服务器成功返回用户请求的数据，该操做是幂等的（Idempotent）。  4 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。  5 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）  6 204 NO CONTENT - [DELETE]：用户删除数据成功。  7 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操做，该操做是幂等的。  8 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。  9 403 Forbidden - [*] 表示用户获得受权（与401错误相对），可是访问是被禁止的。 10 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操做，该操做是幂等的。 11 406 Not Acceptable - [GET]：用户请求的格式不可得（好比用户请求JSON格式，可是只有XML格式）。 12 410 Gone -[GET]：用户请求的资源被永久删除，且不会再获得的。 13 422 Unprocesable entity - [POST/PUT/PATCH] 当建立一个对象时，发生一个验证错误。 14 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将没法判断发出的请求是否成功。 15 502 网关错误 16 503 Service Unavailable 17 504 网关超时

常见状态码

七、应该有返回值，并且格式为统一的json格式

针对不一样操做，向用户返回的结果应该符合规范：

GET/collections：返回资源对象的列表（数组） GET/collections/identity：返回单个资源对象 POST/collections：返回新生成的资源对象 PUT/collections/identity：返回完整的资源对象 PATCH/collections/identity：返回被修改的属性 DELETE/collections/identity：返回一个空文档

返回结果

八、统一描述错误和自定义错误信息

当客户端发生错误时，须要具体告诉客户端错误的信息这个信息用3个东西来定义：错误码，错误信息，当前URL，也能够超过此三个添加本身的错误信息。

九、返回结果中要提供帮助连接，即API最好作到Hypermedia。

十、在url接口中推荐使用Https协议，让网络接口更加安全

（Https是Http的安全版，即HTTP下加入 SSL层，HTTPS的安全基础是SSL，所以加密的详细内容就须要SSL（安全套接层协议））