01 前言

02 RESTful的来源

03 RESTful6大原则

1. C-S架构

2. 无状态

3.统一的接口

4.一致的数据格式

4.系统分层

5.可缓存

6.按需编码、可定制代码（可选）

03 RESTful的7个最佳实践

1. 版本

https://example.com/api/v1/

2.参数命名规范

https://example.com/api/users/today_login 获取今天登陆的用户
https://example.com/api/users/today_login&sort=login_desc 获取今天登陆的用户、登陆时间降序排列

3.url命名规范

https://example.com/api/getallUsers GET 获取所有用户
https://example.com/api/getuser/1 GET 获取标识为1用户信息
https://example.com/api/user/delete/1 GET/POST 删除标识为1用户信息
https://example.com/api/updateUser/1 POST 更新标识为1用户信息
https://example.com/api/User/add POST 添加新的用户

https://example.com/api/users GET 获取所有用户信息
https://example.com/api/users/1 GET 获取标识为1用户信息
https://example.com/api/users/1 DELETE 删除标识为1用户信息
https://example.com/api/users/1 Patch 更新标识为1用户部分信息,包含在body中
https://example.com/api/users POST 添加新的用户

4. 统一返回数据格式

• code——包含一个整数类型的HTTP响应状态码。
• status——包含文本：”success”，”fail”或”error”。HTTP状态响应码在500-599之间为”fail”，在400-499之间为”error”，其它均为”success”（例如：响应状态码为1XX、2XX和3XX）。这个根据实际情况其实是可要可不要的。
• message——当状态值为”fail”和”error”时有效，用于显示错误信息。参照国际化（il8n）标准，它可以包含信息号或者编码，可以只包含其中一个，或者同时包含并用分隔符隔开。
• data——包含响应的body。当状态值为”fail”或”error”时，data仅包含错误原因或异常名称、或者null也是可以的

{
"code": 200,
"message": "success",
"data": {
"userName": "123456",
"age": 16,
"address": "beijing"
  }
}

{
"code": 401,
"message": "error  message",
"data": null
}

public class ApiResult: ApiResult
    {
public new static ApiResult<T> Error(string message)
        {
return new ApiResult<T>
            {
                Code = 1,
                Message = message,
            };
        }
        [JsonProperty("data")]
public T Data { get; set; }
    }
public class ApiResult
    {
public static ApiResult Error(string message)
        {
return new ApiResult
            {
                Code = 1,
                Message = message,
            };
        }

public static ApiResult<T> Ok<T>(T data)
        {
return new ApiResult<T>()
            {
                Code = 0,
                Message = "",
                Data = data
            };
        }
/// <summary>
/// 0 是 正常 1 是有错误
/// </summary>
        [JsonProperty("code")]
public int Code { get; set; }
        [JsonProperty("msg")]
public string Message { get; set; }

        [JsonIgnore]
public bool IsSuccess => Code == 0;
    }

5. http状态码

• 1**请求未成功
• 2**请求成功、表示成功处理了请求的状态代码。
• 3**请求被重定向、表示要完成请求，需要进一步操作。通常，这些状态代码用来重定向。
• 4** 请求错误这些状态代码表示请求可能出错，妨碍了服务器的处理。
• 5**（服务器错误）这些状态代码表示服务器在尝试处理请求时发生内部错误。这些错误可能是服务器本身的错误，而不是请求出错。

6. 合理使用query parameter

比如设计一个最近登陆的所有用户
https://example.com/api/users?recently_login_day=3

搜索用户，并按照注册时间降序
https://example.com/api/users?recently_login_day=3

搜索用户，并按照注册时间升序、活跃度降序
https://example.com/api/users?q=key&sort=create_title_asc,liveness_desc

关于分页，看看博客园开放平台分页获取精华区博文列表
https://api.cnblogs.com/api/blogposts/@picked?pageIndex={pageIndex}&pageSize={pageSize}
返回示例：
[
{
“Id”: 1,
“Title”: “sample string 2”,
“Url”: “sample string 3”,
“Description”: “sample string 4”,
“Author”: “sample string 5”,
“BlogApp”: “sample string 6”,
“Avatar”: “sample string 7”,
“PostDate”: “2017-06-25T20:13:38.892135+08:00”,
“ViewCount”: 9,
“CommentCount”: 10,
“DiggCount”: 11
},
{
“Id”: 1,
“Title”: “sample string 2”,
“Url”: “sample string 3”,
“Description”: “sample string 4”,
“Author”: “sample string 5”,
“BlogApp”: “sample string 6”,
“Avatar”: “sample string 7”,
“PostDate”: “2017-06-25T20:13:38.892135+08:00”,
“ViewCount”: 9,
“CommentCount”: 10,
“DiggCount”: 11
}
]

7. 多表、多参数连接查询如何设计URL

https://example.com/api/orders?order_month=6&order_amount_greater=500&address_city=北京&sort=order_amount_desc&age_min=22&age_max=40

[Route(“api/orders/{address}/{month}”)]

https://example.com/api/orders/beijing/6?order_amount_greater=500&sort=order_amount_desc&age_min=22&age_max=40

请求方式：GET
请求地址：https://api.cnblogs.com/api/blogs/{blogApp}/posts?pageIndex={pageIndex}
(ps:blogApp：博客名)