Restful API 设计原则及其规范

关于 HTTP 动词以及状态码的运用

在此说明一下，此处介绍的允许返回的状态码，仅包含了执行成功的状态码，而没有包含服务器异常、没有权限、参数校验失败等异常状态下的状态码

HTTP Method 允许返回的状态码 说明 GET 200, 404 GET 请求常用于查询数据 POST 200, 201， 409 POST 请求常用于创建资源，但是在其他动词不适用的情况下，可以都使用 POST 请求，例如 /login , /logout PUT 200, 404 PUT 请求常用于修改资源 PATCH 200, 404 PATCH 请求同样用于修改资源，但是它与 PUT 的区别在于 PUT 是修改资源的所有属性， 而 PATCH 用于修改资源中某一个或多个属性 DELETE 200, 204, 404 用于删除资源 其它 其它方法目前较少使用，所以暂时不对其作更多介绍

关于异常情况下 HTTP 返回状态码的说明

Response Status 说明 400 参数错误 401 没有认证 403 没有权限，与401的区别在于 403 是已经通过了认证但是没有权限访问资源 404 找不到相应的资源 405 所请求的 HTTP Method 不被支持 5xx 服务器错误

关于 URL 的设计原则

关于 URL 的设计， 也是本文的重点，下面将一一介绍。

关于资源命名

• 使用名词而不是动词， 在 Rest API 中，我们应该避免使用动词来作为资源名，对于资源操作的动作应该以 HTTP 动词的形式提供。当然，很多操作时没办法直接用简单的增删改查表示，这时，我们就可以使用 POST 来代替，如: /login, /logout 之类的方法都可以用POST 请求。

• 使用复数名词而不是单数，例如对于 category 来说，我们应该使用它的复数形式：categories。

• 名称中所有字母都应该使用小写而不是大写。
• 对于多个单词，应该使用 - （中划线）而不是 _ （下划线）或是驼峰方式进行区分，这里解释一下，因为在 URL 链接中，如果使用下划线作为单词分隔的话，对于用户来说不是很好辨别，因为它很可能和空格混淆。

关于 API 的版本

对于将要对外提供服务的 API 来说， 最好规定它的版本，例如：/v1/users ; 这样对于以后升级API 是非常友好的，因为可以同时部署多个版本的API来避免升级后造成的版本不兼容问题。

关于路径的重复定义问题

举例来说，我们可能有两个资源，用户(user)以及用户组(group), 对于某一个组下面的某一个用户来说，可能会设计这样的 API：/v1/groups/{groupId}/users/{userId} ，这就会与定义的用户API重复： /v1/users/{userId} , 两个 API ，功能都是通过 ID 获取用户，这样就会造成 API 的重复定义，这种情况应该尽量避免。

结语

关于Hypermedia

按照 Restful 风格的指导，我们知道，对于RestAPI，最好做到 Hypermedia， 即在返回值中提供链接，使得用户在不用查询文档的情况下就可以知道下一步该做啥，但在实际的开发中，基本没这样使用过；在实际开发中，一般都会提供 swagger 文档或是其它形式的文档， 这样不仅能提供更详细的信息，而且对于前端开发人员来说，可以直接调用 API 进行测试。所以对于 Hypermedia 来说，此处不展开讲。

关于错误返回值

以下提供我所使用的返回值结构：

{  "message": "错误提示信息",  "status": "自定义错误码",  "timestamp": "时间戳"}

这个返回值用于所有调用API时的异常情况, 包括权限问题， 参数校验失败或是服务器异常等。

关于正常的返回值

一般情况下，都是直接将资源序列化返回，关于序列化的格式，则根据客户端请求决定，通常都是 json， 但是也可以返回 xml。

结语

以上，就是我对于 Restful API 设计的一些浅薄见解，多有不足之处，望大家多多指正。

最后，以下是根据上述原则而设计的一些 API，大家可以下载源码或是在线查看，当然，其中包含也包含了一些其他的技术，在以后的博客中，我会一一介绍。

这里是源码