1-RESTful风格的接口命名规范_ 股票程序化软件自动交易接口

最近实习单位的leader要求我调研一下RESTful风格的1,接口命名规范，然后把项目里的URL名整体规范化修改一下，以下是我调研之后的对于RESTful的了解。

REST是一个术语的缩写，REpresentationalStateTransfer，中文直译是“表征状态转移”。REST是一套风格约定，RESTful是它的形容词形式。比如一套实现了REST风格的1,接口，可以称之为RESTful1,接口。

目前，我们的项目里，基本只有GET和POST两种http方法，如下，无疑浪费了HTTP协议的潜力，而REST则充分利用了HTTP规范中的方法，达到1,接口描述的语义化。

REST描述了HTTP层里客户端和服务器端的数据交互规则；客户端通过向服务器端发送HTTP请求，接收服务器的响应，完成一次HTTP交互。这个交互过程中，REST架构约定两个重要方面就是HTTP请求的所采用方法，以及请求的链接。

REST规范可以简单粗暴抽象成以下两个规则：请求API的URL表示用来定位资源；请求的METHOD表示对这个资源进行的操作；

以下将以这两个规则为基础，描述如何构造一个符合REST规范的请求。

API的url

URL用来定位资源，跟要进行的操作区分开，这就意味着URL不该有任何动词。

下面示例中的get、create、search等动词，都不应该出现在REST架构的后端1,接口路径中。比如：

当我们需要对单个用户进行操作时，根据操作的方式不同可能需要下面的这些1,接口：

/api/getUser/api/updateUser/api/deleteUser/api/resetUser

可能在更新用户不同信息时，提供不同的1,接口，比如：

总结：

以上三种情况的弊端在于：首先加上了动词，肯定是使URL更长了；其次对一个资源实体进行不同的操作就是一个不同的URL，造成URL过多难以管理。

其实当你回过头看“URL”这个术语的定义时，更能理解这一点。URL的意思是统一资源定位符，这个术语已经清晰的表明，一个URL应该用来定位资源，而不应该掺入对操作行为的描述。

在REST架构的链接应该是这个样子：

URL中不应该出现任何表示操作的动词，链接只用于对应资源；URL中应该单复数区分，推荐的实践是永远只用复数；比如GET/api/users表示获取用户的列表；如果获取单个资源，传入ID，比如/api/users/123表示获取单个用户的信息；按照资源的逻辑层级，对URL进行嵌套，比如一个用户属于某个团队，而这个团队也是众多团队之一；那么获取这个用户的1,接口可能是这样：GET/api/teams/123/members/234表示获取id为123的小组下，id为234的成员信息。按照类似的规则，可以写出如下的1,接口/api/teams/api/teams/123/api/teams/123/members/api/teams/123/members/456

API请求的方法

实际上，我们不只有GET和POST可用，在REST架构中，有以下几个重要的请求方法：GET，POST，PUT，PATCH，DELETE。

接下来主要介绍PUT，PATCH和DELETE。

【Update】资源的更新，用于更新的HTTP方法有两个，PUT和PATCH。他们都应当被实现为幂等方法，即多次同样的更新请求应当对服务器产生同样的副作用。

PUT用于更新资源的全部信息，在请求的body中需要传入修改后的全部资源主体；PATCH用于局部更新，在body中只需要传入需要改动的资源字段。

PATCH的作用在于如果一个资源有很多字段，在进行局部更新时，只需要传入需要修改的字段即可。否则在用PUT的情况下，你不得不将整个资源模型全都发送回服务器，造成网络资源的极大浪费。

【Delete】资源的删除，相应的请求HTTP方法就是DELETE。这个也应当被实现为一个幂等的方法。如：DELETE/api/users/123

用于删除服务器上ID为123的资源，多次请求产生副作用都是，是服务器上ID为123的资源不存在。

过滤

REST风格的1,接口地址，表示的可能是单个资源，也可能是资源的集合；当我们需要访问资源集合时，设计良好的1,接口应当接受参数，允许只返回满足某些特定条件的资源列表。

支持提供关键词进行搜索，以及排序

支持根据字段进行过滤

当我们都熟悉且遵循这样的规范后，基本可以看到一个REST风格的1,接口就知道如何使用这个1,接口进行CRUD操作了。比如下面这面这个1,接口就表示搜索ID为123的书馆的书，并且书的信息里包含关键字「game」，返回前十条满足条件的结果。

正确示例

标准的格式是

{version}代表api的版本信息。{domain}是一个你可以用来定义任何技术的区域(例如：安全-允许指定的用户可以访问这个区域)或者业务上的原因(例如：同样的功能在同一个前缀之下。){rest-convention}代表这个域(domai下，约定的rest1,接口集合。

单资源(singular-resourceX)url样例：order/(order即指那个单独的资源X)GET–返回一个新的orderPOST-创建一个新的order，从post请求携带的内容获取值。单资源带id(singular-resourceX/{id})URL样例：order/1(order即指那个单独的资源X)GET–返回id是1的orderDELETE–删除id是1的orderPUT–更新id是1的order，order的值从请求的内容体中获取。复数资源(plural-resourceX/)URL样例:orders/GET–返回所有orders复数资源查找(plural-resourceX/searcURL样例：orders/search?name=123GET–返回所有满足查询条件的order资源。(实例查询，无关联)–order名字等于123的。复数资源查找(plural-resourceX/searchByXXX)URL样例：orders/searchByItems?name=ipadGET–将返回所有满足自定义查询的orders–获取所有与items名字是ipad相关联的orders。单数资源(singular-resourceX/{id}/pluralY)URL样例：order/1/items/(这里order即为资源X，items是复数资源Y)GET–将返回所有与orderid是1关联的items。singular-resourceX/{id}/singular-resourceY/URL样例：order/1/item/GET–返回一个瞬时的新的与orderid是1关联的item实例。POST–创建一个与orderid是1关联的item实例。Item的值从post请求体中获取。singular-resourceX/{id}/singular-resourceY/{id}/singular-resourceZ/URL样例：order/1/item/2/package/GET–返回一个瞬时的新的与item2和order1关联的package实例。POST–创建一个新的与item2和order1关联的package实例，package的值从post请求体中获得。

RESTful风格的接口命名规范