重拾 RESTful API

REST 是什么

Representational State Transfer 数据表现形式地传输

1. 万维网软件架构风格

2. 特指用来创建网络服务

About the REST API - GitHub Docs

Get oriented to the REST API documentation.

https://docs.github.com/en/rest/about-the-rest-api/about-the-rest-api?apiVersion=2022-11-28

REST 限制

客户端-服务器（client-server）

1. 关注点分离

2. 服务端专注数据存储

3. 前端专注用户界面

无状态（Stateless）

1. 用户会话信息均保存在客户端

2. 每次请求必须包括所有信息，不能依赖上下文信息（翻页功能中的下一页必须传入下一页的页码）

3. 服务端不保存会话信息，提升了简单性（代码减少）、可靠性（软件稳定程度以及从故障中恢复正常的能力，但从用户会话来说如果保存在后端处理事故很难恢复）、可见性（模块、接口的透明程度，每次请求包含必要的所有信息）

缓存（Cache）

1. 所有服务端的响应都必须标记为可缓存或者不可缓存（静态资源：图片、字体、样式等为可缓存，动态资源：接口一般为不可缓存）

2. 减少前后端交互，提升性能

统一接口（Uniform Interface）

1. 接口设计尽可能的统一、通用

2. 接口与实现逻辑解耦，使前后端独立开发

分层系统（Layered System）

1. 层与层知道彼此超过一层互不干涉

2. 客户端不知道是和代理还是服务器通信

3. 安全层、负载均衡（流量分发）、缓存层等

按需代码（Code On Demand）

1. 客户端可下载/接收服务端传递的代码（如：js）

统一接口如何设计

资源标识

1. 资源是任何可以命名的事物，比如用户、评论等

2. 每个资源可以通过 URI 被唯一标识

https://api.github.com/users

https://api.github.com/users/i7eo

REST API endpoints for users - GitHub Docs

Use the REST API to get public and private information about authenticated users.

https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#list-users

通过表述来操作资源

1. 表述（Representational），比如：JSON、XML 等

2. 客户端不能直接操作（SQL）服务端资源

3. 客户端应该通过表述（JSON）操作服务端资源

自描述信息

1. 每个消息（请求或响应）必须提供足够的信息让接受者理解

2. 媒体类型（application/json、application/xml 等）

3. HTTP 方法（GET/POST/PATCH（部分替换）/PUT（全量替换）/DELETE）

4. 是否缓存（Cache-Control）

超媒体作为应用状态引擎

1. 超媒体（带文字的链接）

2. 应用状态（一个网页）

3. 引擎（驱动、跳转）

RESTful API 设计

组成要素

1. 基本 URI

2. 标准 HTTP Method

3. 传输媒体类型 JSON/XML

例子

REST API endpoints for users - GitHub Docs

Use the REST API to get public and private information about authenticated users.

https://docs.github.com/en/rest/users/users?apiVersion=2022-11-28#list-users

请求设计规范

1. URI 使用名词，尽可能使用复数，如：/users

2. URI 使用嵌套表示关联关系，如：/users/12/repos/5

3. 使用正确的 HTTP 方法，如 GET/POST/PATCH（部分替换）/PUT（全量替换）/DELETE

4. 不符合上述要求的 CRUD 操作，可考虑使用： POST {资源}/{操作}

响应设计规范

1. 查询（响应筛选项）
例子
https://api.github.com/users?since=100

2. 分页
例子
https://api.github.com/users?page=2&per_page=50

3. 字段过滤（按照请求中的参数指定，指定返回结果）
例子
https://api.github.com/users/i7eo?fields=name

4. 状态码
例子
1. 运行时错误（500）
2. 逻辑错误，如找不到（404）、表中无查询字段即先决条件失败（412）、无法处理实体即参数格式不对（422）
3. 处理成功无返回即删除成功（204）

5. 错误处理（错误信息，message/errors）

安全

1. HTTPS

2. 用户鉴权（JWT）

3. 限流（limit rate）

开发者友好

1. 文档

2. 超媒体

最佳实践

Best practices for using the REST API - GitHub Docs

Follow these best practices when using GitHub's API.

https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api?apiVersion=2022-11-28

参考

How to Design a REST API - Step by Step Guide

Follow these steps to design a REST API - Identify the Object Model, Create Resource URIs, Determine Representations, and Assign HTTP Methods.

https://restfulapi.net/rest-api-design-tutorial-with-example/

Best practices for REST API design - Stack Overflow

REST APIs are one of the most common kinds of web interfaces available today. They allow various clients including browser apps to communicate with services via the REST API. Therefore, it's very important to design REST APIs properly so that we won't run into problems down the road. We have to take into account security, performance, and ease of use for API consumers.

https://stackoverflow.blog/2020/03/02/best-practices-for-rest-api-design/

Web API design best practices - Azure Architecture Center

Learn the best practices for designing web APIs that support platform independence and service evolution.

https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design