《ASP.ENT Core 与 RESTful API 开发实战》-- 读书笔记（第1章）

第 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) 。