一种软件架构风格-restful-api

Posted 2020-09-29 alan-alan

定义：

1. 一种软件架构风格，设计风格而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。
2. 基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

 

1. 前端设备层出不穷（手机、平板、桌面电脑、其他专用设备）。
2. restful-api 是目前比较成熟的一套互联网应用程序的API设计理论
3. API的就是程序员的UI，和其他UI一样，你必须仔细考虑它的用户体验

相关概念知悉：

http动词

1. GET（SELECT）：从服务器取出资源（一项或多项）。
2. POST（CREATE）：在服务器新建一个资源。
3. PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
4. PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
5. DELETE（DELETE）：从服务器删除资源。

 

1. HEAD：获取资源的元数据。
2. OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

Filtering

1. ?limit=10：指定返回记录的数量
2. ?offset=10：指定返回记录的开始位置。
3. ?page=2&per_page=100：指定第几页，以及每页的记录数。
4. ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
5. ?animal_type_id=1：指定筛选条件

设计原则

1. 如果员工ID由客户端来指定，我们可以发送PUT请求；如果员工ID由服务端生成，我们一般发送POST请求。
2. 如果PUT提供的资源不存在，则做添加操作，否则做修改。
3. 根据请求携带的信息识别提交和希望返回的资源表示

 

1. 作为资源标识的URI最好具有“可读性”
2. 标识资源的URI应该具有“可寻址性（Addressability）”
3. URI是资源的唯一标识,相同的资源可以具有多个标识。

为每一个资源定义一个具有良好可读性的uri

 1 // var url = "GET /ticket/12embed=customer.name,assigned_user"
 2 // message 报文
 3 {
 4   "id" : 12,
 5   "subject" : "I have a question!",
 6   "summary" : "Hi, ....",
 7   "customer" : {
 8     "name" : "Bob"
 9   },
10   assigned_user: {
11    "id" : 42,
12    "name" : "Jim",
13   }
14 }

 

设计误区

 1 /*
 2 
 3 1.最常见的一种设计错误，就是URI包含动词
 4 2.另一个设计误区，就是在URI中加入版本号
 5 
 6 正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务
 7 因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。
 8 版本号可以在HTTP请求头信息的Accept字段中进行区分
 9 
10 */
11 
12 // http://www.example.com/app/1.0/foo
13 // http://www.example.com/app/1.0/accounts/1/transfer/500/to/2
14 // http://www.example.com/app/1.0/accounts/transaction? from=1&to=2&amount=500.00
15 // http://www.example.com/app/accounts/transaction?from=1&to=2&amount=500.00

 

 

Status Codes

1. 200 OK - [GET]：服务器成功返回
2. 400：用户发出的请求有错误
3. 401：表示用户没有权限（令牌、用户名、密码错误）。
4. 403 表示用户得到授权（与401错误相对），但是访问是被禁止的。
5. 404 ：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
6. 500：服务器发生错误，用户将无法判断发出的请求是否成功。

 

Error handling

如果状态码是4xx，就应该向用户返回出错信息

 1 {
 2   "code" : 1234,
 3   "message" : "Something bad happened :-(",
 4   "description" : "More details about the error here"
 5 }
 6 // 2
 7 {
 8   "code" : 1024,
 9   "message" : "Validation Failed",
10   "errors" : [
11     {
12       "code" : 5432,
13       "field" : "first_name",
14       "message" : "First name cannot have fancy characters"
15     },
16     {
17        "code" : 5622,
18        "field" : "password",
19        "message" : "Password cannot be blank"
20     }
21   ]
22 }

 

 

参考资料

http://www.ruanyifeng.com/blog/2011/09/restful

http://www.cnblogs.com/artech/p/3506553.html

http://blog.jobbole.com/41233/