前端API规范

## 资源（Resources） 

---

REST的名称"表现层状态转化"中，省略了主语。"表现层"其实指的是"资源"（Resources）的"表现层"。
所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

## HTTP 谓词

---

RESTful Web API采用了同一的接口，所以其成员体现为针对同一资源的操作。对于Web来说，针对资源的操作通过HTTP方法来体现。

1. C (create) -  POST   新增一个资源
1. R (retrieve) -  GET   读取资源
1. U (update) - PUT   更新资源
1. D (delete) - DELETE  删除资源

## HTTP 状态码

---

针对客户端向Web服务器发送的任意一个HTTP请求，不论在何种情况下得到一个响应，每个响应均具有一个由3位数字表示的状态码和相应的描述文字。不同数值的状态码体现了不同类型的响应状态，W3C对响应状态码的范围作了如下的规范。

- 100~199：信息状态码，代表请求已被接受，需要继续处理。
- 200~299：成功状态码，代表请求已成功被服务器接收、理解、并接受。
- 300~399：重定向状态码，代表需要客户端采取进一步的操作才能完成请求。
- 400~499：客户端错误状态码，代表了客户端看起来可能发生了错误，妨碍了服务器的处理。
- 500~599：服务器错误状态码，代表了服务器在处理请求的过程中有错误或者异常状态发生，也有可能是服务器意识到以当前的软硬件资源无法完成对请求的处理。


## 返回结果

---

- 当 http 状态为 20X，一般为 200 时，既认定当前请求成功，返回结果为正确业务数据
- 当 http 状态为 4XX，一般为 400 时，既认定当前请求出现异常，其返回结果为异常原因。401表示认证失败
- 当 http 状态为 5XX，  其中500服务器内部错误

 ### 单个资源

     //单个资源
       {
            id:11,                  //int
            name:'aaa',             //string
           createTime:1231233000,  //datetime
           account:222.21,         //float
       }

      ### 数组资源

```javascript
    //列表资源
    [
        {id:1,name:"张三"},
        {id:2,name:"李四"},
        {id:3,name:"王五"},
    ]


    //列表资源带分页
    {
        count:3,
        list:[
            {id:1,name:"张三"},
            {id:2,name:"李四"},
            {id:3,name:"王五"},
        ]
    }   

### 异常返回

> HTTP:400 时，使用以下格式

    //异常返回
    {
        message:'输入参数有误',
        code:'1001'
    }

## URL
***
 1. URI不要包含动词
 1. URI不要包含动词
 1. URI不要包含动词

  - 重要的说3遍


### 单资源( singular-resourceX )

   > url样例： /order

   1. GET – 返回一个新的order

   1. POST- 创建一个新的order，从post请求携带的内容获取值。

### 单资源带id(singular-resourceX/{id} )

> URL样例：order/1 ( order即指那个单独的资源X )

1. GET – 返回id是1的order

1. DELETE – 删除id是1的order

1. PUT – 更新id是1的order，order的值从请求的内容体中获取。

### 复数资源(plural-resourceX/)

 > URL样例: /orders

 1. GET – 返回所有orders

 ### 复数资源查找(plural-resourceX/search)

 > URL样例： /orders/search?name=123

 1. GET – 返回所有满足查询条件的order资源。(实例查询，无关联) – order名字等于123的。

### 单数资源(singular-resourceX/{id}/pluralY)

> URL样例： /order/1/items/ (这里order即为资源X，items是复数资源Y)

1. GET – 将返回所有与order id 是1关联的items。

### singular-resourceX/{id}/singular-resourceY/

 > URL样例：/order/1/item/

 1. GET – 返回一个瞬时的新的与order id是1关联的item实例。

 2. POST – 创建一个与order id 是1关联的item实例。Item的值从post请求体中获取。