Restful API规范

术语

• URI：Uniform Resource Identifier（统一资源标识符）
• URL：Uniform Resource Locators（统一资源定位地址）
• REST: Representational State Transfer (表现层状态转移)
• ROA：Resource Oriented Architecture（面向资源架构）

介绍

REST是Representational State Transfer的简称，中文翻译为“表征状态转移”。是web服务的一种架构风格，一种设计风格，是一种思想。REST从资源的角度类审视整个网络，它将分布在网络中某个节点的资源通过URL进行标识，客户端应用通过URL来获取资源的表征，获得这些表征致使这些应用转变状态。Rest与技术无关，不是针对某一种编程语言。甚至有人提出一种全新的结构理念，面向资源架构（ROA：Resource Oriented Architecture）。

Restful API设计

1. 语法

schema://user:password@host:port/vsersion/directory/file.extension

2. 通讯协议

API与用户的通信协议，总是使用HTTPs协议。

3.域名

• https://api.example.com 尽量将API部署在专用域名（会存在跨域问题）
• https://example.org/api/ API很简单

4. 版本

• URL，如：https://api.example.com/v1/
• 请求头 跨域时，引发发送多次请求

5. URI

路径，视网络上任何东西都是资源，均使用名词表示（可复数）

• https://api.example.com/v1/zoos
• https://api.example.com/v1/animals
• https://api.example.com/v1/employees

URI是网站UI的一部分，因此，可用的网站应该满足这些URL要求

• 简单，好记的域名
• 简短（short）的URI
• 容易录入的URI
• URI能反应站点的结构
• URI是可以被用户猜测和hack的（也鼓励用户如此）
• 永久链接，Cool URI don’t change

6. Mehtod

• GET ：从服务器取出资源（一项或多项）
• POST ：在服务器新建一个资源
• PUT ：在服务器更新资源（客户端提供改变后的完整资源）
• PATCH ：在服务器更新资源（客户端提供改变的属性）
• DELETE ：从服务器删除资源

7. 过滤

通过在url上传参的形式传递搜索条件

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

8. 状态码

REST的另一重要部分就是为既定好请求的类型来响应正确的状态码。如果你对HTTP状态码陌生，以下是一个简易总结。当你请求HTTP时，服务器会响应一个状态码来判断你的请求是否成功，然后客户端应如何继续。以下是四种不同层次的状态码：

• 2xx = Success（成功）
  • 200 – OK (默认的)
  • 201 – Created（已创建）
  • 202 – Accepted (已接受：常用语删除请求)
• 3xx = Redirect（重定向）
• 4xx = User error（客户端错误）
  • 400 –请求出错（语法格式有误或服务器无法理解此请求）
  • 401 – 未授权(需要登录)
  • 404 – 找不到 (找不到所请求的文件或脚本)
  • 405 – 不允许此方法(错误的 HTTP方法)
  • 409 – 冲突 (IE尝试以PUT请求创建相同的资源时)
• 5xx = Server error（服务器端错误）