resulful规范_Restful API设计规范及实战【说的比较清楚了】

Restful API的概念在此就不费口舌了，博友们网上查哈定义文章很多，直入正题吧：

首先抛出一个问题：

判断id为 用户下，名称为 使命召唤14(COD14) 的产品是否存在(话说我还是很喜欢玩类似二战的使命召唤这款额，题外话...)？如果这个问题出现在 MVC 项目中，我想我们一般会这样设计：

api/products/isexist/{userId}/{productName}

我想你应该发现一些问题了，这种写法完全是 MVC 的方式，但并不适用于 WebAPI，主要有三个问题：

Route 定义混乱，完全违背 REST API URI 的一些设计原则。Action 命名不恰当。bool 返回值不合适。对于上面的三个问题，我们分别来探讨下。

1. URI 设计首先，我们知道在 REST API 中，URI 代表的是一种资源，它的设计要满足两个基本要求，第一名词而非动词，第二要能清晰表达出资源的含义，

换句话说就是，从一个 URI 中，你可以很直接明了的知道访问的资源是什么，我们再来看我们设计的 URI：

api/products/isExist/{userId}/{productName}

这是神马玩意啊？？？这种设计完全违背 URI 原则，首先，我们先梳理一下，我们想要请求的资源是什么？没错，是产品(Products)，但这个产品是某一个用户下的，

所以用户和产品有一个上下级关系，访问产品首先得访问用户，这一点要在 URI 中进行体现，其次，我们是获取产品？还是判断产品是否存在？这个概念是不同的，

产品的唯一标识和用户一样，都是 id，在 URI 的一般设计中，如果要访问某一唯一标识下的资源(比如 id 为 1 的 product)，会这样进行设计：

api/products/{id}

HttpClient 请求中会用 HttpGet 方法(api/products/1)，这样我们就可以获得一个 id 为 1 的 product，但现在的场景是，获取产品不通过唯一标识，而是通过产品名称，难道我们要这样设计：

api/products/{productName}

咋看之下，这样好像设计也没毛病啊，但总觉得有些不对劲，比如如果再加一个产品大小，难道要改成这样：api/products/{productName}/{productSize}，这种设计完全是不恰当的，上面说到，

URI 代表的是一种资源，通过 URI 获取资源的唯一方式是通过资源的唯一标识，除此之外的获取都可以看作是对资源的查询(Query)，所以，针对我们的应用场景，URI 的设计应该是这样(正确)：

格式标准: api/users/{userId}/products:

示 例 : api/users/1/products?productName=使命召唤COD14

上面的 URI 清晰明了的含义：查询 id 为 1 用户下名称为 COD14 的产品。

2. Action 命名对于 IsExist 的命名，如果没有很强的强迫症，其实也是可以接受的，因为 WebAPI 的 URI 并不会像 MVC 的 Route 设计那样，在访问的时候，URL 一般会默认 Action 的名字，所以，

在 WebAPI Action 设计的时候，会在 Action 前面加一个 Route 属性，用来配置 URI，也就是说每一个 Action 操作会对应一个 URI 请求操作，这个请求操作也就是 HTTP 的常用方法。

如果我们想把 IsExist 改掉，那用什么命名会好些呢？Action 的命名和 HTTP 方法一样，比如 Get 就是 Get，而不是 GetById，Get 是动词，表示它对资源的一种操作，具体是通过什么进行操作？

在参数中可以很直观的进行反应，一般会在 HelpPage 中进行注释说明。

IsExist 的含义还是判断资源是否存在，其本质上来说就是去获取一个资源，也就是 Get 操作，所以，在 WebAPI Action 中对这样的命名，我们直接使用 Get 会好一下，或者使用 Exist。

3. 请求返回bool 一般是用在项目方法中的返回值，如果用在 HTTP 请求中，就不是很恰当了。

上面只是介绍了简单的设计场景，回归正题，继续：

设计方法及原则：

1. 使用HTTP方法：

HTTP1.1的规范定义了8个动词，然而HTTP作为一个规范并没有被严格地遵守着，在大多数情况下POST是可以完成除任何种类的请求，所以现在很多的API设计都是只是用GET和POST来调用API，

在这种情况下，一般的做法是使用GET用来获取资源，其他的行为都是用POST来完成，而为了区别不同的行为，往往在API的Uri中加入动词，如百度推送的如下API：

[ POST ] /rest/3.0/app/del_tag

功能

删除一个已存在的tag

参数

参数名类型必需限制描述

tag

string

是

1~128字节，但不能为‘default’

标签名称

返回值

名称类型描述

tag

string

标签名称

result

number

状态 0：创建成功； 1：创建

更清晰API设计的可能会使用GET POST PUT DELETE四种方法分别代表“查询、添加、更新、删除”等四个动作，这在概念上是符合HTTP规范的，如Google的如下API：

DELETE https://www.googleapis.com/bigquery/v2/projects/datasets/?key={YOUR_API_KEY}

在我看来，没有绝对的好与不好。如果使用第一种方法，那么只要保证Ur