《ASP.ENT Core 与 RESTful API 开发实战》-- 读书笔记（第1章）
2021-10-22 16:42:43

第 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

​
​