Section-1 通过Github认识RESTful api

Lesson-1 REST是什么以及它的6个限制

REST是什么

REST是万维网软件架构风格，它既不是协议，也不是规范，它是用来创建网络服务的一套约定

为什么叫REST

REST，是英文 Representational State Transfer 的缩写
Representational - 数据的表现形式（Json/Xml）
State - 当前状态或者数据
Transfer - 数据传输

REST - 六个限制

1. 客户端-服务器（client-server）,也叫cs架构

• 关注点分离
• 服务端专注数据存储，提升了简单性
• 前端专注用户界面，提升了可移植性

2. 无状态

• 所有用户会话信息都保存在客户端
• 每次请求必须包括所有信息，不能依赖上下文信息
• 服务端不用保存会话信息，提升了简单性、可靠性、可见性

3. 缓存

• 所有服务端响应都要被标为可缓存或不可缓存
• 减少前后端交互，提升了性能

4. 统一接口（Uniform InterFace）

• 接口设计尽可能统一通用，提升了简单性、可见性
• 接口与现实解耦，使前后端可以独立开发迭代

5. 分层系统（Layered System）

• 每层只知道相邻的一层，后面隐藏的就不知道了
• 客户端不知道是和代理还是真实服务器通信
• 其它层：安全层、负载均衡、缓存层等

6. 按需代码（Code-On-Demand 可选）

• 客户端可以下载运行服务端传来的代码（比如JS）
• 通过减少一些功能，简化了客户端

---

Lesson-2 统一接口的限制

资源的标识

• 资源是任何可以命名的事物，比如用户、评论等
• 每个资源可以通过URI被唯一的标识，比如 https://api.github.com/users

通过表述来操作资源

• 表述就是Representation，比如Json、XML等
• 客户端不能直接操作（比如SQL）服务端资源
• 客户端应该通过表述（比如Json）来操作资源
• 参考github接口风格

自描述信息

• 每个消息（请求或响应）必须提供足够的信息让接受者理解
• 媒体类型（application/json、application/xml）
• HTTP方法：GET(查)、POST(增)、DELETE(删)
• 是否缓存：Cache-Control
• 参考github接口风格

超媒体作为应用状态引擎

• 超媒体：带文字的链接
• 应用状态：一个网页
• 引擎：驱动、跳转
• 合起来：点击超链接跳转到另一个网页
• 参考github接口风格

---

Lesson-3 RESTful API简介

RESTful API就是符合REST风格的API

RESTful API具体什么样子

• 基本的URI，如 https://api.github.com/users
• 标准HTTP方法，如GET，POST，PUT，PATCH，DELETE
• 传输的数据媒体类型，如json/xml

现实举例

• GET/users - 获取user列表
• GET/users/12 - 查看某个具体的user
• POST/users - 新建一个用户
• PUT/users/12 - 更新user 12
• DELETE/user/12 - 删除user 12
  PATCH 和 PUT 区别在于，PATCH用于局部更新，PUT用于整体更新
• 参考github接口风格

---

Lesson-4 RESTful API设计最佳实践

请求设计规范

• UIR使用名词，尽量用复数，如/users
• URI使用嵌套表示关联关系，如/user/12/repos/5
• 使用正确的HTTP方法，如GET/POST/PUT/DELETE
• 不符合 CRUD(增删改查)的情况：POST/action/子资源
• 参考github接口风格

响应设计规范

• 查询 - 每一个响应都是可以被过滤的，加上限制条件，只返回符合要求的数据
• 分页 - 基本同上
• 字段过滤 - 只返回指定的字段信息
• 状态码
  • 2开头代表正确
  • 3开头代表重定向
  • 4开头代表客户端错误
  • 5开头代表服务端错误
• 错误处理

安全

• HTTPS
• 鉴权
• 限流
• 参考github接口风格

开发者友好

• 文档
• 超媒体