Rest接口设计之个人理解

前言

关于Rest是什么，本文不做任何介绍。这里记录的是：在多年的工作经验中，从书上学到的、代码中看到的接口规范的个人理解与总结。有不正确的地方，欢迎大家指正。
在当前的项目开发中，不同模块之间通常采用API来访问数据，如何约束和管理开发人员交付的接口风格保持一致，开发人员之间彼此能够快速理解、减少不必要的沟通呢？我相信大部分团队在项目开发之初都会针对团队现状制定一些基础接口规范，这样在一定程度上可以明确职责、加快项目进度。当然我也遇到过一些反例，相互之间扯皮的时间都够完成大部分需求开发了。言归正传，既然说到了接口规范了，我就以当前流行的Rest约束作为模板，谈谈我的理解。

REST规范

关于REST API接口，我的总结是：
REST API接口 = 资源地址（URI） + 请求方法（HTTP VERB）
大家可能会说，你是不是少了请求参数？没有，之所以不提参数，因为它不直接影响接口的设计与规范。
一个标准、规范、友好的API接口，应该做到资源地址与请求方法隔离，互不影响。如何理解这名话，请继续往下看。

资源地址（URI）

1. 为什么是URI，而不是URL？
   在REST原则中，最重要的是定义资源，资源定义好了，其对应的标识符也就有了，那接口的目的就是通过资源的标识符去访问这些资源。因此，这里需要的是资源标识符（URI），而不是资源定位符（URL）。
2. 资源地址由名词构成
   明确了上述概念，就不难理解为什么资源地址由名词构成了。比较好的示例大家可以参考豆瓣API和GitHub API，可以说是我见过的最标准的API。说白了，接口地址就是资源标识符，因此，它理应由名词组成，不应夹杂着动词出现。大家在实际项目中肯定见过这样的反例：http://xxx.com/abc/def/getUserList或者http://xxx.com/abc/def/createXXX。其实，这就是典型的资源地址与请求方法耦合的例子，开发者可能会说，这样写可以很明确的告诉使用者接口的目的或效果。但实际上呢？这属于多此一举，而且严重违反了REST的设计理念。因为，HTTP协议中已经定义好了资源的增、删、改、查方法。
3. 资源由复数表示
   定义资源时，通常是对某个对象或服务的抽象，而接口实际上是对抽象后的对象或服务的集合的操作，因此，强烈建议在定义资源地址时使用复数，如http://xxx.com/api/v1/users，表示对用户资源的基本操作。

请求方法

REST原则（或约束）其实是对HTTP协议的补充，本质上也是HTTP请求。HTTP协议已经定义好了常用的增、删、改、查方法，分别对应HTTP请求的POST、DELETE、PUT和GET方法。设计出上一小节那样反例的同学要么是不清楚HTTP协议、要么就是不理解REST原则。因此，遵守最基本的HTTP协议方法就可以让你在无形中成为了REST约束的实践达人。看，就是这么简单。

最佳示例

方法	示例	说明
GET	/users	返回用户列表，后面可添加分页信息，如?limit=10&offset=0
GET	/users/c12dl3	返回ID为c12dl3的用户详情
POST	/users	创建新用户
PUT	/users/c12dl3	修改ID为c12dl3的用户信息
DELETE	/users/c12dl3	删除ID为c12dl3的用户

写在最后

最核心的两点已经介绍完了，其实关于REST原则还有很多内容，但都没有以上内容可以让人更直观的理解，而且有些特性在实践中很难被真正落实，所以不提也罢。