Restful架构介绍

前言

互联网软件采用的是“客户端/服务器”的模式，通过互联网通信，具有高延时、高并发等的特点。由于当下web应用发展迅速，我们必须使用一种更高效的接口规范来统一我们的接口

Restful架构是目前较为流行的一种互联网软件架构。它结构清晰、符合标准、易于理解，拓展方便。

起源

REST这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的。

Fielding是一个非常重要的人，他是HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。所以，他的这篇论文一经发表，就引起了关注，并且立即对互联网开发产生了深远的影响。

规范

• 资源路径

主要是URL的定义，要设计出优雅的、易读的rest接口路径

• URL中不能有动词

接口路径当中不应该包含动词

• URL结尾不能包含“/”

虽然有一部分的web组件和框架将平等对待URL结尾有或无“/”的接口请求，但本质上是两个不同的URL。如果URL不同，那么资源也是如此，因此REST API必须生成和传递精确的URL，绝不能容忍有任何的差错

• “/”必须用来指示层级关系

接口路径中使用“/”来表示资源的层级关系

• 若想提高URL的可读性，应使用“-”而不是_

有时候为了能够让其他人理解，我们需要把URL变的更加可读，那么应该使用“-”而不是“_”

• URL路径中首选小写字母

URL中尽可能不出现大写字母

• URL路径名词均为复数

例如：/api/resources，对路径名词统一使用复数

• RESTful API对资源的操作

对于rest api资源的操作，由HTTP动词表示

• CURD操作

GET/POST/PUT/PATCH/DELETE

• 资源过滤

一般用于分页，XXXX?page=1&page-size=10

• 返回状态码推荐标准的HTTP状态码

  • 200 OK 服务器返回用户请求的数据，该操作是幂等的
  • 201 CREATED 新建或者修改数据成功
  • 204 NOT CONTENT 删除数据成功
  • 400 BAD REQUEST 用户发出的请求有问题，该操作是幂等的
  • 401 Unauthoried 表示用户没有认证，无法进行操作
  • 403 Forbidden 用户访问是被禁止的
  • 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误
  • 500 INTERNAL SERVER ERROR 服务器内部错误，用户将无法判断发出的请求是否成功
  • 503 Service Unavailable 服务不可用状态，多半是因为服务器问题，例如CPU占用率大，等等

• 返回结果

  • GET /collections 返回资源列表
  • GET /collections/:id 返回单独的资源
  • POST /collections 返回新生成的资源对象
  • PUT /collections/:id 返回完整的资源对象
  • PATCH /collections/:id 返回被修改的属性
  • DELETE /collections/:id 返回一个空文档