RESTful API

Restful API

Restful API 是一种互联网软件架构设计的设计规范，设计指南，设计风格和设计原则。

由于前后端分离，前后端通信为了有一个统一的机制，restful api作为制定接口标准的规范而产生了。

设计原则以及规范

• 协议。API与用户的通信协议，总是使用HTTPs协议

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

• 版本。应将API版本号放入URL中

• 统一接口。对业务数据增删改查（CRUD），Restful用HTTP方法与对应。

  CRUD	HTTP Methods
  Create（增）	POST
  Read（查）	GET
  Update（改）	PUT
  Delete（删）	DELETE

• URL中只能有名词，不能出现动词。这是因为在REST要求对资源的操作由HTTP方法给出，而方法是由HTTP请求报文头部给出的，自然不需要在URL中暴露操作方式。资源名应该使用复数形式，使用users而不是user。

• 状态码。服务器向用户返回的状态码和提示信息，常见的有以下一些

  状态码	提示信息
  200	ok-[GET]:服务器成功返回用户请求的数据，该操作是幂等的，就是无论你访问多少次都是一样的。
  201	CREATED-[POST/PUT/PATCH]: 用户新建或修改数据成功
  204	NO CONTENT-[DELETE]: 用户删除数据成功
  302	Found-[*]:临时重定向（请求的资源已被分配新的URL，希望用户本次使用新的URL）
  400	INVALID REQUEST-[POST/PUT/PATCH]:用户发出的请求有错误，服务器没有进行新建或者修改数据的操作，该操作也是幂等的
  401	Unauthorized-[*]:表示用户没有权限（令牌、用户名、密码错误）
  403	Forbidden-[*]:表示用户得到授权（与401错误相对），但是访问是被禁止的
  404	NOT FOUND-[*]:用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。简单说就是请求资源路径不存在。
  500	Internal Server Error-[*]:服务器在执行请求时发生错误
  503	Service Unavailable-[*]:服务器暂时处于超负载或是正在进行停机维护，现在无法处理请求

  状态码类别

  • 1XX（信息性状态码）表示接收的请求正在处理
  • 2XX（成功状态码）表示请求正常处理完毕
  • 3XX（重定向状态码）表示需要进行附加操作以完成请求
  • 4XX（客户端错误状态码）表示服务器无法处理请求
  • 5XX（服务器错误状态码）表示服务器处理请求出错

• 错误处理。如果状态码是4XX，就应该向用户返回出错信息。返回的信息中将error作为键名，出错信息作为值即可。

RESTful API 的好处

• 规范API设计
• 增强API的可读性
• 方便前后端协作