RESTful API 概述

基本概念

REST 英文全称：Representational State Transfer，直译为：表现层状态转移。首次是由Roy Thomas Fielding在他2000年的博士论文中提出。

REST是一种描述网络中client和server之间的资源交互方式。

而RESTful API就是完全遵循REST方式的一套API设计规范，简单来说，通过API来描述资源的访问方式：

• 通过HTTP URL描述访问什么资源
• 通过HTTP METHOD描述对资源的交互方式
• 通过HTTP CODE描述资源的交互结果

幂等性

幂等性(Idempotence)本身是一个数学概念，在HTTP/1.1规范中幂等性是指

Methods can also have the property of “idempotence” in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request.  如果某个方法调用一次或多次产生的副作用是相同的，那么这个方法具有幂等性。

比如在HTTP中使用GET获取某个资源，无论调用多少次，产生的额外效果都是从服务器获取资源，所以GET方式具有幂等性。

而POST方法用于在服务器上创建一个资源，由于最终创建的结果每次都是不同的，所以POST不具有幂等性。

但是PUT方法却是幂等的，因为每次调用产生的效果都是对资源进行更新。

安全方法

安全方法是指不修改资源的 HTTP 方法。譬如，当使用 GET 或者 HEAD 作为资源 URL，都必须不去改变资源的表现形式。

注意：安全方法并不是指服务器上的资源完全不变，而是指资源的表现形式。

比如GET方法导致数据上报，关联的一些数据记录等，他实际上是改变了服务器上的某些附加资源的，但是这并不会改变资源的表现形式。

HTTP中的安全方法有：

• GET
• HEAD
• PATCH

RESTful API设计规则

HTTP URL

HTTP URL只用于描述访问的资源，而不应该包含对资源的交互方式。HTTP URL的Best Practice:

• 将API部署在专用的域名上
• 不使用任何大写字符
• 不使用下划线_，可使用中划线-代替
• 参数列表要进行编码
• 不应该出现描述资源交互方式的动词，应尽量使用描述资源的名词
• URI中的名词表示资源集合，应该使用复数形式
• 应该避免资源层级太深，可以适当使用参数减少层级
• 使用斜杆/表示资源之间的层级关系
• 在URI的末尾避免使用/
• 避免在URI中使用文件扩展名
• 如果有必要，需要在