Web API在过去的几年里非常盛行，因为它有着语法简单、规范化和轻量级的优点，因为得到广泛的推崇，很多过往的技术手段都慢慢转换为使用Web API来开发。而Web API通常使用的设计方式是RESTful（Representational State Transfer，表述性状态转移），它使用了典型的HTTP方法，诸如GET、POST、PUT和DELETE来对资源进行管理和交互。

这里列出设计RESTful API的10个最佳实践。

1.在API中使用名词，而不是动词。

在RESTful中，API描述的应该是资源，而不是动作，因此在API应使用名词去描述资源，而不是动词用动词去描述动作。

RESOURCE	GET:READ	POST:CREATE	PUT:UPDATE	DELTE:DELETE
/cars	返回一个car的列表	创建一个新的car	更新car的信息	删除所有的car
/cars/yanggb	返回指定的car	Method not allowed(405)	更新指定的car的信息	删除指定的car

而不是使用动词，比如下面的API是不推荐的：

/getAllCars 获取所有车辆
/createNewCar 创建新的车辆
/deleteAllRedCars 删除所有红色的车辆

2.GET方法和查询参数不应该改变资源状态。

GET方法的API应该是幂等的，即不应该改变资源的状态，无论请求多少次，返回的结果都是一致的。

如果要改变资源的状态，应该使用POST、PUT和DELETE方法。

3.使用名词的复数形式。

不要混合使用名词的单数和复数形式，而应该为所有的资源从一开始就保持使用复数形式。

/cars 替代 /car
/users 替代 /user
/products 替代 /product
/settings 替代 /setting

4.为关系使用子资源。

假如资源连接到其他资源，则应该使用子资源的形式来设计API。

GET /cars/711/drivers 返回711车的驱动器列表
GET /cars/711/drivers/4 返回711车的#4驱动

5.使用HTTP头决定序列化格式。

在客户端和服务端都需要知道使用什么格式来进行通信，这个格式应该在HTTP头中指定。

Content-Type：定义请求的格式。

Accept：定义允许的响应格式的列表。

6.使用HATEOAS。

HATEOAS（Hypermedia as the Engine of Application State）是REST架构风格中最复杂的约束，也是构建成熟REST服务的核心。它是一个指导原则，规定超文本链接应该被用于在API中创建更好的资源导航。

{
    "id": 711,
    "manufacturer": "bmw",
    "model": "X5",
    "seats": 5,
    "drivers": [{
        "id": "23",
        "name": "yanggb",
        "links": [{
            "rel": "self",
            "href": "/api/v1/drivers/23"
        }]
    }]
}

在上面的返回结果中，包含了超文本链接资源的信息。

7.为集合提供过滤、排序、字段选择和分页。

过滤：为所有字段或者查询语句提供独立的查询参数。

GET /cars?color=red 返回红色车的列表
GET /cars?seats<=2 返回两座车的列表

排序：允许跨越多字段的正序或者倒序排列。

GET /cars?sort=-manufactorer,+model 返回排序的车辆列表

字段选择：只列出需要的字段。一些情况下，只需要在列表中查询几个有标识意义的字段，并不需要从服务端把所有字段的值都请求出来，因此需要API支持选择查询字段的能力。这样也可以在一定程度上提高网络传输的性能与响应速度。

GET /cars?fields=manufacturer,model,id,color 返回需要的车辆信息字段的列表

分页：使用offset和limit来获取固定数量的资源结果，当其中一个参数没有出现时，应该提供各自的默认值，比如默认取第一页，或者默认取20条数据。

GET /cars?offset=10&limit=5 返回第10页的5条车辆记录列表
GET /cars?&limit=5 返回前5条车辆记录列表
GET /cars?&offset=5 返回第5页的车辆记录列表（默认单页数量）

8.版本化API。

确保强制实行API版本，并且不要发布一个没有版本的API。使用简单的序列数字，比如v1，避免使用2.5.0这样的形式（点分隔符）。

/blog/api/v1

9.使用HTTP状态码处理错误。

忽略错误处理的API是很难使用的，简单的返回500和调用堆栈是非常不友好的，同时这些错误信息在一定程度上来说也是无用的。

使用HTTP状态码

HTTP标准中提供了70多个状态来描述返回值，但是我们并不需要用到其中的全部，只需要了解其中一些比较常用的就可以了。

200 – OK – 一切正常
201 – OK – 新资源已经被创建
204 – OK – 资源删除成功

304 – 没有变化，客户端可以使用缓存数据

400 – Bad Request – 调用不合法，确切的错误应该在error payload中描述
401 – 未认证，调用需要用户通过认证
403 – 不允许的，服务端正常解析和请求，但是调用被回绝或者不被允许
404 – 未找到，指定的资源不存在
422 – 不可指定的请求体 – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失

500 – Internal Server Error – 标准服务端错误，API开发人员应该尽量避开这种错误

使用error payloads

所有的请求异常都应该被映射到error payloads中。

{
    "errors": [{
        "userMessage": "Sorry, the requested resource does not exist",
        "internalMessage": "No car found in the database",
        "code": 34,
        "more info":"http://www.yanggb.com/blog/api/v1/errors/12345"
    }]
}

10.允许重写HTTP方法。

一些代理只支持GET和POST方法。为了在这种限制下使用RESTful API（GET/POST/PUT/DELETE），则API需要重写HTTP方法。

比如可以使用自定义的X-HTTP-Method-Override HTTP头来重写POST方法。

 

"感情实在是场无法掌控的事，没有逻辑，没有规律，更没顺理成章的必然。"