Rustful接口开发

什么是api

api简称接口。

就是一些预先定义的函数，目的是能够让应用程序或者开发人员具有能够访问指定网络资源的能力，而又无需关心访问的源码，或理解内部工作机制的细节。

api的产生

web Android iOS

由一个地方统一提供API接口，多个平台直接调用这个API接口获取信息

Restful规范

1.协议

rest API与用户的通信协议，总是使用http协议。

（对安全要求较高的话，可以使用HTTPS）

2.域名

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

https://api.example.com

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

https://example.com/api/

3.版本

应该讲API的版本号放入URL。

https://api.example.com/version/

另一种做法，将版本号放在http头信息中，但不如放入URL方便和直观。

4.路径

路径又称“终点（endpoint）”，表示API的具体网址。

在restful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库中的表名对应。一般来说，数据库中的表都是同种记录的”集合“，所以API中的名词也应该使用复数。

举例来说，有一个api提供动物园的信息，还包括各种动物和雇员的信息，则它的路径应该设计成如下：

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

5.http动词

对于资源的具体操作类型，由http动词表示。

常用的http动词有如下四个：

post（create）：在服务器新建一个资源
delete（delete）：从服务器删除资源
put（update）：在服务器更新资源（客户端提供改变后的完整资源）
get（select）：从服务器取出资源（一项或多项）

6.过滤信息

如果记录数量很多，服务器不可能都将他们返回给用户，API应该提供参数，过滤返回结果。

？limit=10；指定返回记录的数量
？offset=10；指定返回记录的开始位置
？page=28per_page=100:指定第几页，以及每页的记录数。
？sortby=name&order=asc：指定返回结果按照那个属性排序，以及排序顺序。
？animal_type_id=1:指定筛选条件

7.状态码

常见状态码：

• 200（ok）【get】：服务器成功返回用户请求的数据
• 201（created）【post/put/patch】：用户新建或修改数据成功
• 202（created）【*】：表示一个请求已经进行后台排队（异步任务）
• 204（no content）【delete】：用户删除数据成功
• 302：请求的资源临时从不同的URL响应请求。由于这样的重定向是临时的，客户端应当继续向原有地址发送以后的请求。只有在cache-control或者express中进行了指定的情况下，这个响应才是可缓存的
• 304：如果客户端发送了一个带条件的GET 请求且该请求已被允许，而文档的内容（自上次访问以来或者根据请求的条件）并没有改变，则服务器应当返回这个304状态码。简单的表达就是：服务端已经执行了GET，但文件未变化。
• 400（invalid request）【post/put/patch】：用户发出的请求有错误，服务器没有进行新建或修改数据的操作
• 401（unauthorized）【*】：表示用户没有权限（令牌，用户名，密码错误）
• 403（forbidden）【*】：表示用户得到授权（与401错误相对），但是访问是被禁止的
• 404（not found）【*】：请求失败，请求所希望得到的资源未被在服务器上发现
• 406（not acceptable）【get】：用户请求的格式不可得（比如用户请求json格式，但是只有xml格式）
• 410（gone）【get】：用户请求的资源被永久删除，且不会在得到的。
• 422（unprocesable entity）【post/put/patch】：当创建一个对象时，发生一个验证错误。
• 500（internal server error）【*】：服务器发生错误，用户将无法判断出的请求是否成功（一般来说，这个问题都会在服务器端的源码出现错误时出现）

8.错误处理

如果产生错误，就应该向用户返回出错误信息，一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
error:"Invalid API key"
}

9.返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET/collection:返回资源对象的列表
GET/collection/resource:返回单个资源对象
POST/collection:返回新生成的资源对象
PUT/collection/resource：返回完整的资源对象
PATCH/collection/resource：返回完整的资源对象
DELETE/collection/resource：返回一个空文档