Restful API简介

Restful API

定义

REST：表述（编者注：通常译为表征）性状态转移。指的是一组架构约束条件和原则。如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。RESTFUL适用于移动互联网厂商作为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。

特点

1、每一个URI代表1种资源；
2、客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
3、通过操作资源的表现形式来操作资源；
4、资源的表现形式是XML或者HTML；
5、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。

Restful api的设计

1. uri与url的区别

   // 对资源的描述构成了uri
   // 1.使用名词，如：user，students，emp
   http://api.example.com/class-management/students
   http://api.example.com/device-management/managed-devices/{device-id}
   // 2.http method对应不同的请求动作（数据库或者业务逻辑）
   // 3.使用连字符（ - ）而不是（_）来提高URI的可读性
   http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //更易读
   http://api.example.com/inventory_management/managed_entities/{id}/install_script_location //更容易出错
   // 4.使用小写字母
   http://api.example.org/my-folder/my-doc
   // 5.不要使用文件扩展名 文件扩展名看起来很糟糕，不会增加任何优势。删除它们也会减少URI的长度。没理由保留它们。
   http://api.example.com/device-management/managed-devices.xml // 不要使用它 
   http://api.example.com/device-management/managed-devices // 这是正确的URI 
   // 6.使用查询组件过滤URI集合很多时候，我们会遇到需要根据某些特定资源属性对需要排序，过滤或限制的资源集合的要求。为此，请不要创建新的API - 而是在资源集合API中启用排序，过滤和分页功能，并将输入参数作为查询参数传递。例如：
   http://api.example.com/device-management/managed-devices
   http://api.example.com/device-management/managed-devices?region=USA
   http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
   http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
   // 7.不要在末尾使用/ 作为URI路径中的最后一个字符，正斜杠（/）不会添加语义值，并可能导致混淆。最好完全放弃它们。
   // 8.使用http状态码定义api执行结果
   1xx：信息
   通信传输协议级信息。
   2xx：成功
   表示客户端的请求已成功接受。
   3xx：重定向
   表示客户端必须执行一些其他操作才能完成其请求。
   4xx：客户端错误
   此类错误状态代码指向客户端。
   5xx：服务器错误
   服务器负责这些错误状态代码。
   // 9.api版本定义
   当我们需要对现有的api接口升级的时候，因为该api接口已经投入使用，所以新添加的业务可能无法保证兼容原来的逻辑，这个时候就需要新的接口，而这个接口一般表示对原来的接口的升级（不同版本），那版本怎么定义呢？
   URI版本控制（推荐）
   http://api.example.com/v1
   http://apiv1.example.com
   使用自定义请求标头进行版本控制
   Accept-version：v1
   Accept-version：v2
   使用Accept header 进行版本控制
   Accept:application / vnd.example.v1 + json
   Accept:application / vnd.example + json; version = 1.0
   

2. 无状态

   无状态通过将API部署到多个服务器，有助于将API扩展到数百万并发用户。任何服务器都可以处理任何请求，因为没有与会话相关的依赖。（集群）

   无状态使得REST API不那么复杂 - 可以删除所有服务器端状态同步逻辑。（删除session，清理多余空间）

   无状态API也很容易缓存。特定软件可以通过查看该一个请求来决定是否缓存HTTP请求的结果。从先前的请求中获得的状态可能会影响这个请求的可缓存性，这并不存在任何不确定性。它提高了应用程序的性能。

   服务器永远不会忘记每个客户端身份”，因为客户端会在每个请求中发送所有必要的信息。（携带token）

---

接口操作

Verd	描述
HEAD（SELECT）	只获取某个资源的头部信息
GET（SELECT）	获取资源
POST（CREATE）	创建资源
PATCH（UPDATE）	更新资源的部分属性（很少用，一般用POST代替）
PUT（UPDATE）	更新资源，客户端需要提供新建资源的所有属性
DELETE（DELETE）	删除资源