JAVA REST API

参考链接：
CodeSail | RESTful API Design
Create REST APIs with JAX-RS 2.0
菜鸟教程 | RESTFul API
RestFul API 命名

什么是REST

REST是REpresentational State Transfer的缩写，是一种分布式超媒体系统的架构风格。

怎么写REST API

1. 基本概念

• 使用HTTP方法，常用的有：GET(读取), POST(新增), PUT/PATCH(更新), DELETE(删除)。
• 面向资源的，一个资源代表一个URI，如 /articles。
• API由HTTP方法和URI组成，如 GET /articles。
• API可以表示一个资源或操作。如 POST /articles 表示“新增一个article“。
• 状态码有5个类别：1xx 相关信息, 2xx 成功, 3xx 重定向, 4xx 客户端错误 and 5xx 服务器错误。

2. 响应格式

不要返回纯文本，推荐JSON。

3. 不要使用“动词“

GET /articles       /**正确示范**/
GET /getArticles    /**错误示范**/

POST /articles          /**正确示范**/
POST /createArticles    /**错误示范**/

4. 用复数形式表示一个集合

GET /artiles/{id}      /**正确示范**/
GET /artile/{id}       /**错误示范**/

POST /artiles     /**正确示范**/
POST /artile       /**错误示范**/

5. 返回错误信息

服务器错误时，在返回体中返回错误信息。

{
    "error":  "您没有权限。"
}

6. 关注状态码

服务器错误时，不要返回200状态码。

/**错误示范**/ 
/**前端需要结合状态码和status判断服务器响应是否成功**/
HTTP/1.1 200 OK
Content-Type: text/html

{
    "code": "-1",
    "data": {
        "error": "Expected at least two items in list."
    }
}

/**正确示范**/

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "Expected at least two items in list."
}

7. 使用一致性的状态码

例如，你在某处使用POST /articles 创建article成功，返回 “201 Created“，那么其它地方使用POST 创建成功时，也必须返回 “201 Created“。

/**推荐**/

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content

8. 避免多级URI，使用QueryString过滤集合

 /**普通示范**/ 
GET /authors/1/articles    
GET /authors/1/categories/2

 /**更好的示范**/ 
GET /articles?author_id=12   
GET /authors/1?categories=2

10. “401 Unauthorized“ 和 “403 Forbidden“ 的区别

• 当用户未提供授权，返回401 Unauthorized。
• 当用户使用错误的授权，返回403 Forbidden。

11. 使用“202 Accepted“

• 资源将会创建，但是目前还在创建中。
• 资源已经创建过了。

12. 不要使用尾斜杠“/“

GET /articles     
GET /articles    /**更优雅**/

13. 使用“-“提高URI的可读性

GET /my_doc/my_file    /** 避免使用"_" **/
GET /my-doc/my-file    /**更优雅**/

14. 使用小写字母提高URI的可读性

GET /myDoc/myFile      /**不推荐**/
GET /my-doc/my-file    /**更优雅**/

15. 不要文件后缀

GET /myDoc/myFile.xml      /**不推荐**/
GET /my-doc/my-file        /**更优雅**/