resful协议1
一、重要概念：
RESTFul API已经是现在互联网里对外开放接口的主流模式，可参考：
豆瓣API https://developers.douban.com/wiki/?title=api_v2
GitHub https://developer.github.com/v3/
分享关于resful协议：
https://www.jianshu.com/p/294fcc945db7
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是一种架构风格，其核心是面向资源
首先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 提高可扩展性
2、resful的10大设计规范
总结一下什么是RESTful架构：
（1）每一个URI代表一种资源；
（2）客户端和服务器之间，传递这种资源的某种表现层；
（3）客户端通过四个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。
1、路径（接口命名）
在RESTful架构中，每个网址代表一种资源（resource），所以在url接口中尽量要使用名词，不要使用动词，而且所用的名词往往与数据库的表格名对应。
一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也尽量使用复数。
2、动作
可以根据Http不同的method，进行不同的资源操作（5种方法：GET / POST / PUT / DELETE / PATCH）
1 GET （SELECT）：从服务器检索特定资源，或资源列表。 2 POST （CREATE）：在服务器上创建一个新的资源。 3 PUT （UPDATE）：更新服务器上的资源，提供整个资源。 4 PATCH （UPDATE）：更新服务器上的资源，仅提供更改的属性。 5 DELETE （DELETE）：从服务器删除资源。
3、版本控制
版本控制：API一定要有版本号。不一定要在URL路径在，可以再hearder加也可以在 url参数加。不过我认为放到路径好一些。如：http://api.example.com/v1.0/foo
4、过滤信息（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 的含义是相同的。
5、url中可以体现这是个API接口
https://www.example.com/api/
6、状态码（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 网关超时
7、 应该有返回值，而且格式为统一的json格式
针对不同操作，向用户返回的结果应该符合规范：
GET/collections：返回资源对象的列表（数组） GET/collections/identity：返回单个资源对象 POST/collections：返回新生成的资源对象 PUT/collections/identity：返回完整的资源对象 PATCH/collections/identity：返回被修改的属性 DELETE/collections/identity：返回一个空文档
8、统一描述错误和自定义错误信息
当客户端发生错误时，需要具体告诉客户端错误的信息这个信息用3个东西来定义：错误码，错误信息，当前URL，也可以超过此三个添加自己的错误信息。
9、返回结果中要提供帮助链接，即API最好做到Hypermedia。
10、在url接口中推荐使用Https协议，让网络接口更加安全
（Https是Http的安全版，即HTTP下加入 SSL层，HTTPS的安全基础是SSL，因此加密的详细内容就需要SSL（安全套接层协议））
11、测试与生产环境分开：不仅仅是部署不同的站点，更重要的是把这两个站点用不同的域名表示，生产环境则是api.XXX.com是api的经典域名模式，开发版本前面加一个dev
