读C#代码整洁之道笔记06_API的设计与开发

1. API

1.1. Application Programming Interface

1.1.1. 应用程序编程接口

1.2. 一组可以在不同的应用和程序中共享的可复用的程序库

1.3. 由REST服务提供的API=RESTful API

1.3.1. Representational State Transfer，REST

1.3.1.1. 表述性状态传递

1.3.2. Roy Fielding在2000年引入

2. RESTful API

2.1. 统一接口

2.1.1. 接口用于识别资源，并使用表述来操作资源

2.2. 客户端-服务器

2.2.1. 只有客户端能够调用的API是可见的

2.2.2. 与系统的其他部分独立

2.3. 无状态

2.3.1. 没有会话也没有历史

2.4. 可缓存

2.4.1. 资源必须声明其缓存性，这样就可以更快地访问资源

2.4.1.1. 获得速度的提升

2.4.1.2. 降低服务的负载

2.5. 分层系统

2.5.1. 每一层仅仅具备一种职责

2.6. 可选的可执行代码

2.6.1. 服务器可以通过传输可执行代码临时扩展或者自定义客户端的功能

2.7. 所以

2.7.1. 不要假定最终用户是具备特定级别经验的程序员

2.7.2. 不必一次性创建完美的API

2.7.3. 高价值的资产

2.7.3.1. 收费服务

2.7.4. 可以永久有效

3. API代理

3.1. 介于客户端和API中间的类

3.2. API开发者和使用该API的开发人员之间的API契约

4. API设计准则

4.1. 基本准则

4.1.1. API包含资源

4.1.1.1. 资源会形成集合

4.1.1.2. 资源应当使用复数形式的名词

4.1.1.3. API终结点（endpoint）是资源的地址

4.1.1.3.1. URL

4.1.1.3.2. 只能够包含复数名词

4.1.1.3.3. 不能包含动词或动作

4.1.2. GET请求来获得资源

4.1.3. HEAD请求来获得头部信息

4.1.3.1. 头部信息中应当始终包含调用者的标识信息

4.1.4. POST请求插入或者保存新的资源

4.1.5. PUT请求替换资源

4.1.6. PATCH更新或修改一个资源或者资源集合

4.1.7. DELETE请求来删除资源

4.1.8. 使用查询参数保持资源精简

4.1.9. API的版本可以在URL中体现

4.1.10. JSON是首选的资源表述方式

4.1.11. 应当始终为API启用HTTPS（TLS）

4.1.12. 使用API代理

4.1.12.1. 安全和性能的因素

4.1.12.2. 避免暴露数据库的架构

4.1.12.2.1. 发送到客户端的响应不应与数据库的结构一致

4.1.13. 应当提供使用文档与范例

4.2. 明确定义软件边界

4.2.1. 领域驱动开发

4.2.2. 应当公开的唯一信息就是接口的契约以及API终结点

4.3. 高质量API文档

4.3.1. 文档记录不足时，代码重复会成为一个真正的问题

4.3.2. 应当注意标记为弃用或过时的代码

4.3.3. Swagger工具

4.3.3.1. 设计：设计API，并确保API模型符合基于标准的规范

4.3.3.2. 创建：使用C#创建文档可重用的API

4.3.3.3. 编写文档：为开发人员编写可交互的文档

4.3.3.4. 测试：方便地对API进行测试

4.3.3.5. 标准化：使用公司的规范对API架构进行约束

4.4. 传递不可变结构体而非可变对象

4.4.1. 结构体比对象运行更快并且不可变对象是线程安全的

5. RAML

5.1. RESTful API建模语言

5.2. 一种基于YAML格式的新规范

6. 使用API密钥保护API

6.1. Azure Key Vault

6.1.1. Azure 中几个关键管理解决方案之一

6.1.2. 机密管理

6.1.3. 密钥管理

6.1.4. 证书管理

6.2. 范例API项目——股息日历（略）

6.2.1. 实践是学习的最佳途径