第 1 章 REST 简介
1.1 API 与 REST
API 是一个系统向外暴露或公开的一套接口，通过这些接口，外部应用程序能够访问该系统
REST 是一种基于资源的架构风格，任何能够命名的对象都是一个资源，如 user，一个资源具有一个统一的资源标识符（URI），如 user/1234，通过 URI 能够标识并访问该资源
REST 定义了6个架构约束：
- 客户端-服务器
- 统一接口
- 分层系统
- 缓存
- 无状态
- 按需编码
统一接口约束本身又由4个子约束组成：
- 资源的标识
- 通过表述操作资源
- 自描述消息
- 超媒体作为应用程序状态引擎
1.2 HTTP 协议
基于 TCP/IP 协议的应用层协议
浏览网页的过程，就是通过 HTTP 协议来传递浏览器与服务器之间的请求与响应的
HTTP 协议采用请求/响应模型
HTTP 协议采用明文传输数据，这种方式并不安全，所以后来设计了 HTTPS 协议
统一资源定位符（URL）代表网络上一个特定的资源
对于一个 URL，如 http://www.xxx.com/images/logo.png
它由以下几个部分组成：
- http://，这一部分是 URL 协议，指明了如何访问一个特定的资源
- www.xxx.com，这一部分是主机名，告诉浏览器所要访问资源所在的服务器名称
- /images/logo.png，这一部分是 URL 路径，它指向服务器上具体的资源
- 端口号，在主机后面，以冒号隔开，这一部分通常省略，服务器在这个端口上监听 HTTP 请求
- 查询字符串，URL 中 “?” 后面的参数部分
- 锚部分，也称片段，在 “#” 后面的内容，用于指明一个资源的特定的位置
当 HTTP 服务器对请求返回响应时，它不仅仅返回资源本身，也会在响应中指明资源的内容类型（Content Type），也称为媒体类型
要指定内容类型，HTTP 依赖于 MIME 标准，表示文档的性质和格式
常用的 MIME 类型如下：
- text/plain: 纯文本
- text/html: HTML
- image/jepg: JEPG 图片
- image/png: PNG 图片
- application/json: JSON格式数据
HTTP 请求消息和响应消息具有相似的结构：
- 起始行：描述执行的请求，或者对应的状态，成功或失败
- HTTP 消息头：请求或响应的相关属性、配置、对消息正文的描述等
- 空行：指明消息头已经发送完毕
- 消息正文：包含请求数据，或响应中资源的表述
请求起始行包括：
- HTTP 方法
- 请求目标
- HTTP 版本
响应起始行包括：
- 协议版本
- 状态码
- 状态文本
常见的 HTTP 请求方法有：GET、POST、PUT、DELETE、PATCH（部分更新）、HEAD、OPTIONS
HTTP 状态码由3个数字组成，用于指明 HTTP 请求的结果
根据其表述意义，状态码可以分为以下5类：
- 1xx：信息，服务器收到请求，需要请求方继续执行操作
- 2xx：成功：服务器成功执行客户端所请求的操作
- 3xx：重定向：需要进一步的操作以完成请求
- 4xx：客户端错误：请求包含语法错误或请求内容不正确
- 5xx：服务端错误：服务器在处理请求的过程中发生了错误
1.3 REST 最佳实践
首先，在实现 RESTful 系统时，应正确地使用 HTTP 方法、HTTP 消息头和 HTTP 状态码
除了原则以外，在设计资源的 URI 时也应该注意以下原则：
- 使用名词的复数表示一个资源集合
- 使用斜线 ”/“ 用来表示资源之间的层次关系
- 对资源的增删改查等操作名称不应该包含在 URL 中
- 如果一个操作无法对应到资源的某个操作上，此时可以适当地在 URI 中包含动词，但仍然应该基于一个资源的标识符
- 查询字符串可以用来对资源进行筛选、搜索或分页查询
- URI 应使用小写字母
- URI 中可以使用中划线 ”-“ 来增加其可读性
- URI 中不应使用下划线 ”_“ ，因为会使得 URI 点击时下划线不可见
- URL 末尾不应包含斜线 ”/“ ，因为没意义而且可能造成歧义
1.4 其他问题
在 RESTful API 中，JSON 和 XML 是最常用到的两种资源表述格式
JSON 是一种轻量级的数据交换格式，数据使用名称/值来表示，中间用冒号隔开
JSON 数据项的值的类型可以是下列类型：
- 数字
- 字符串
- 逻辑值
- 数组
- 对象
- null
XML 与 HTML 语言很相似，包含标签、属性等元素，而且有非常严格的层次结构，一个标签必须同时具有起始标签与结束标签，允许自定义标签
XML 文档必须包含根元素，该元素是文档中其他元素的父元素，文档中的所有元素形成一棵文档树
XML 每个标签之间还必须要正确的嵌套，另外，标签名区分大小写，标签允许包含一个或多个属性，每个属性的值必须使用引号
JSON 比 XML 更简洁，容易解析，但是不支持注释，扩展性不如 XML
RESTful API 添加版本有以下4中方式：
- 使用 URI 路径，如 api/v1/users
- 使用查询字符串，如 api/users?version=1
- 使用自定义消息头，如 Accept-version:v1
- 使用 Accept 消息头，如 Accept:application/json;v=2.0
本作品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。
欢迎转载、使用、重新发布，但务必保留文章署名 郑子铭 （包含链接： http://www.cnblogs.com/MingsonZheng/ ），不得用于商业目的，基于本文修改后的作品务必以相同的许可发布。
如有任何疑问，请与我联系 (MingsonZheng@outlook.com) 。