KID-G commented on code in PR #1502: URL: https://github.com/apache/apisix-website/pull/1502#discussion_r1109283228
########## blog/zh/blog/2023/02/08/what-is-restful-api.md: ########## @@ -0,0 +1,265 @@ +--- +title: "RESTful API 为何成为顶流 API 架构风格？" +authors: + - name: "孙毅" + title: "Author" + url: "https://github.com/litesun"; + image_url: "https://github.com/litesun.png"; +keywords: +- RESTful +- Apache APISIX +- API +description: 本文将介绍什么是 RESTful API 以及我们如何使用它。 + +tags: [Ecosystem] +--- + +> 本文将介绍什么是 RESTful API 以及我们如何使用它。 + +<!--truncate--> + +> 作者[孙毅](https://github.com/litesun)，API7.ai 技术工程师，Apache APISIX Committer + +万物互联的世界充满着各式各样的 API ，如何统筹规范 API 至关重要。[RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer) 是目前世界上最流行的 API 架构风格之一，它可以帮助你实现客户端与服务端关注点分离，让前后端各自迭代，提升管理效率；其无状态的特性可以让应用更容易扩展，更容易的实现缓存策略从而提升系统性能和用户体验。本文将介绍什么是 RESTful API 以及我们如何使用它。 + +首先，抛开 API 这个概念，我们来聊聊在生活中如何传递信息。 + +当你在商店将钱拿给老板告诉他你需要买电池，老板在收到钱后在货架上找到电池并递给你。一个买电池的交易顺利完成。 + +计算机软件则通过 API 来完成信息的传递，先来看维基百科定义： + +> An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. + +软件 A 通过 API 向软件 B 发起请求，软件 B 在查询自己资源后将请求的响应内容通过 API 返回 A。 + +软件 A 通过 API 向软件 B 发起请求就好比你跟老板说你需要电池，软件 B 在将数据返回给软件 A 就好比老板找到电池后将电池给你。 + +这一过程软件 B 不需要知道软件 A 为什么要数据，就好比商店老板不会问你买电池的目的。软件 A 也不需要知道 B 软件的数据是怎么找到的，就好比你买电池的时候你也不会问老板电池从哪里进货一样。每个软件之间通过 API 传递信息，各司其事，使得程序世界变得有序可靠。 + +## 什么是 RESTful API + +Roy Fielding 在他 2000 年的博士论文《建筑风格和基于网络的软件架构设计》中定义了REST（Representational state transfer），REST 架构风格定义了六个指导性约束。一个符合**部分**或**全部**约束的系统被松散地称为 RESTful。 + + + (图片来源：Seobility) + +### REST 的约束条件（长龙在排版时可以考虑一键截图 or 分点>横向叙述） + +|约束条件|详述|优势| +|:----|:----|:----| +|Client–server architecture|通过将用户界面问题与数据存储问题分开，提高了跨多个平台的用户界面的可移植性，并通过简化服务器组件提高了可扩展性。|1. 客户端、服务端解耦。<br>2. 提升用户平台跨平台的可移植性。<br>3. 提升服务器端的可拓展性。| +|Statelessness|客户端的每个请求到服务器必须包含请求所需的所有信息，并且不能利用服务器上存储的任何上下文，会话状态完全保存在客户端。|1. 易扩展，无会话依赖，任何服务器可以处理任何请求。<br>2. 易缓存，提升程序性能。| +|Cacheability|要求请求响应中的数据被隐式或显式标记为可缓存或不可缓存。如果一个响应是可缓存的，那么客户端缓存就被授予为以后的等效请求重用该响应数据的权利。|1. 减少带宽。<br>2. 减少延迟。<br>3. 减少服务器负载。<br>4. 隐藏网络状态。| +|Layered system|通过约束组件行为允许架构由分层层组成，这样每个组件都不能“看到”超出它们与之交互的直接层。通过将系统知识限制在单个层，降低了整个系统的复杂性并促进了底层独立性。|1. 降低整个系统的复杂性。<br>2. 促进底层的独立性。<br>3. 可方便的实施负载均衡。<br>4. 可将业务逻辑和安全策略解耦。| +|Code on demand (optional)|允许通过下载和执行小程序或脚本形式的代码来扩展客户端功能。|1. 提高系统的可扩展性。| +|Uniform interface|主要包含四点：<br>1. Resource identification in requests.<br>客户能够通过请求中包含的 URI 来识别一个资源，将服务端资源和客户端请求资源解耦。<br>2. Resource manipulation through representations.<br>当客户端拥有一个资源的表示，如 URI，那么就有足够的信息来修改或者删除资源。<br>3. Self-descriptive messages.<br>每个消息都包括足够的信息来告知客户客户端该如何处理该信息。<br>4. Hypermedia as the engine of application state ([HATEOAS](https://github.com/api7/contents/blob/691305a1293991d7b0b39a0ac9a7a655c935778a/blog/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FHATEOAS)).<br>客户端不需要任何额外的编码通过服务端返回的资源链接，就可以使得用户获取所有的资源。|1. 简化了整体系统架构。<br>2. 提高了交互的可见性。| + +## RESTful API 最佳实践 + +强调组件间的 **统一接口** 是 REST 架构风格与其他基于网络的风格区分开来的核心特征，基于此特征，本文梳理了RSETful 最佳实践，以帮助你更好的设计 API。 + +### 路径名称避免动词 + +使用 HTTP 方法来表达资源操作行为，而不是将行为动词定义到路径中。 + +```shell +// Good +curl -X GET http://httpbin.org/orders + +// Bad +curl -X GET "http://httpbin.org/getOrders"; +``` + +* GET 获取指定 URI 的资源信息 + +```shell +// 代表获取当前系统的所有订单信息 +curl -X GET http://httpbin.org/orders + +// 代表获取订单编号为 1 的订单详情信息 +curl -X GET http://httpbin.org/orders/1 +``` + +* POST 通过指定的 URI 创建资源 + +```plain + // 代表创建一个名称为 order 的资源 +curl -X POST http://httpbin.org/orders \ + -d '{"name": "awesome", region: "A"}' \ +``` + +* PUT 创建或全量替换指定 URI 上的资源 + +```shell + // 代表将 id 为 1 的 order 进行数据替换 +curl -X PUT http://httpbin.org/orders/1 \ + -d '{"name": "new awesome", region: "B"}' \ +``` + +* PATCH 执行一个资源的部分更新 + +```shell + // 代表将 id 为 1 的 order 中的 region 字段进行更改，其他数据保持不变 +curl -X PATCH http://httpbin.org/orders/1 \ + -d '{region: "B"}' \ +``` + +* DELETE 通过指定的 URI 移除资源 + +```shell + // 代表将 id 为 1 的 order 删除 +curl -X DELETE http://httpbin.org/orders/1 +``` + +### URI 使用复数形式 + +若使用单数的形式来表示获取某一类资源，例如： + +```shell +curl -X GET "http://httpbin.org/order"; +``` + +使用单数形式，会使用户产生该系统中只有一个 order 的困惑，用复数形式在逻辑上则顺畅很多。 + +```shell +curl -X GET "http://httpbin.org/orders"; +``` + +### 善用 HTTP 状态码 + +HTTP 标准定义个状态码，大致可以分为以下几类： + +|状态码|含义| +|:----|:----| +|2xx|成功，操作被成功接收并处理| +|3xx|重定向，需要进一步的操作以完成请求| +|4xx|客户端错误，请求包含语法错误或无法完成请求| +|5xx|服务器错误，服务器在处理请求的过程中发生了错误| Review Comment: > ditto I don’t know what‘s wrong with this table ########## blog/zh/blog/2023/02/08/what-is-restful-api.md: ########## @@ -0,0 +1,265 @@ +--- +title: "RESTful API 为何成为顶流 API 架构风格？" +authors: + - name: "孙毅" + title: "Author" + url: "https://github.com/litesun"; + image_url: "https://github.com/litesun.png"; +keywords: +- RESTful +- Apache APISIX +- API +description: 本文将介绍什么是 RESTful API 以及我们如何使用它。 + +tags: [Ecosystem] +--- + +> 本文将介绍什么是 RESTful API 以及我们如何使用它。 + +<!--truncate--> + +> 作者[孙毅](https://github.com/litesun)，API7.ai 技术工程师，Apache APISIX Committer + +万物互联的世界充满着各式各样的 API ，如何统筹规范 API 至关重要。[RESTful API](https://en.wikipedia.org/wiki/Representational_state_transfer) 是目前世界上最流行的 API 架构风格之一，它可以帮助你实现客户端与服务端关注点分离，让前后端各自迭代，提升管理效率；其无状态的特性可以让应用更容易扩展，更容易的实现缓存策略从而提升系统性能和用户体验。本文将介绍什么是 RESTful API 以及我们如何使用它。 + +首先，抛开 API 这个概念，我们来聊聊在生活中如何传递信息。 + +当你在商店将钱拿给老板告诉他你需要买电池，老板在收到钱后在货架上找到电池并递给你。一个买电池的交易顺利完成。 + +计算机软件则通过 API 来完成信息的传递，先来看维基百科定义： + +> An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. + +软件 A 通过 API 向软件 B 发起请求，软件 B 在查询自己资源后将请求的响应内容通过 API 返回 A。 + +软件 A 通过 API 向软件 B 发起请求就好比你跟老板说你需要电池，软件 B 在将数据返回给软件 A 就好比老板找到电池后将电池给你。 + +这一过程软件 B 不需要知道软件 A 为什么要数据，就好比商店老板不会问你买电池的目的。软件 A 也不需要知道 B 软件的数据是怎么找到的，就好比你买电池的时候你也不会问老板电池从哪里进货一样。每个软件之间通过 API 传递信息，各司其事，使得程序世界变得有序可靠。 + +## 什么是 RESTful API + +Roy Fielding 在他 2000 年的博士论文《建筑风格和基于网络的软件架构设计》中定义了REST（Representational state transfer），REST 架构风格定义了六个指导性约束。一个符合**部分**或**全部**约束的系统被松散地称为 RESTful。 + + + (图片来源：Seobility) + +### REST 的约束条件（长龙在排版时可以考虑一键截图 or 分点>横向叙述） + +|约束条件|详述|优势| +|:----|:----|:----| +|Client–server architecture|通过将用户界面问题与数据存储问题分开，提高了跨多个平台的用户界面的可移植性，并通过简化服务器组件提高了可扩展性。|1. 客户端、服务端解耦。<br>2. 提升用户平台跨平台的可移植性。<br>3. 提升服务器端的可拓展性。| +|Statelessness|客户端的每个请求到服务器必须包含请求所需的所有信息，并且不能利用服务器上存储的任何上下文，会话状态完全保存在客户端。|1. 易扩展，无会话依赖，任何服务器可以处理任何请求。<br>2. 易缓存，提升程序性能。| +|Cacheability|要求请求响应中的数据被隐式或显式标记为可缓存或不可缓存。如果一个响应是可缓存的，那么客户端缓存就被授予为以后的等效请求重用该响应数据的权利。|1. 减少带宽。<br>2. 减少延迟。<br>3. 减少服务器负载。<br>4. 隐藏网络状态。| +|Layered system|通过约束组件行为允许架构由分层层组成，这样每个组件都不能“看到”超出它们与之交互的直接层。通过将系统知识限制在单个层，降低了整个系统的复杂性并促进了底层独立性。|1. 降低整个系统的复杂性。<br>2. 促进底层的独立性。<br>3. 可方便的实施负载均衡。<br>4. 可将业务逻辑和安全策略解耦。| +|Code on demand (optional)|允许通过下载和执行小程序或脚本形式的代码来扩展客户端功能。|1. 提高系统的可扩展性。| +|Uniform interface|主要包含四点：<br>1. Resource identification in requests.<br>客户能够通过请求中包含的 URI 来识别一个资源，将服务端资源和客户端请求资源解耦。<br>2. Resource manipulation through representations.<br>当客户端拥有一个资源的表示，如 URI，那么就有足够的信息来修改或者删除资源。<br>3. Self-descriptive messages.<br>每个消息都包括足够的信息来告知客户客户端该如何处理该信息。<br>4. Hypermedia as the engine of application state ([HATEOAS](https://github.com/api7/contents/blob/691305a1293991d7b0b39a0ac9a7a655c935778a/blog/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FHATEOAS)).<br>客户端不需要任何额外的编码通过服务端返回的资源链接，就可以使得用户获取所有的资源。|1. 简化了整体系统架构。<br>2. 提高了交互的可见性。| + +## RESTful API 最佳实践 + +强调组件间的 **统一接口** 是 REST 架构风格与其他基于网络的风格区分开来的核心特征，基于此特征，本文梳理了RSETful 最佳实践，以帮助你更好的设计 API。 + +### 路径名称避免动词 + +使用 HTTP 方法来表达资源操作行为，而不是将行为动词定义到路径中。 + +```shell +// Good +curl -X GET http://httpbin.org/orders + +// Bad +curl -X GET "http://httpbin.org/getOrders"; +``` + +* GET 获取指定 URI 的资源信息 + +```shell +// 代表获取当前系统的所有订单信息 +curl -X GET http://httpbin.org/orders + +// 代表获取订单编号为 1 的订单详情信息 +curl -X GET http://httpbin.org/orders/1 +``` + +* POST 通过指定的 URI 创建资源 + +```plain + // 代表创建一个名称为 order 的资源 +curl -X POST http://httpbin.org/orders \ + -d '{"name": "awesome", region: "A"}' \ +``` + +* PUT 创建或全量替换指定 URI 上的资源 + +```shell + // 代表将 id 为 1 的 order 进行数据替换 +curl -X PUT http://httpbin.org/orders/1 \ + -d '{"name": "new awesome", region: "B"}' \ +``` + +* PATCH 执行一个资源的部分更新 + +```shell + // 代表将 id 为 1 的 order 中的 region 字段进行更改，其他数据保持不变 +curl -X PATCH http://httpbin.org/orders/1 \ + -d '{region: "B"}' \ +``` + +* DELETE 通过指定的 URI 移除资源 + +```shell + // 代表将 id 为 1 的 order 删除 +curl -X DELETE http://httpbin.org/orders/1 +``` + +### URI 使用复数形式 + +若使用单数的形式来表示获取某一类资源，例如： + +```shell +curl -X GET "http://httpbin.org/order"; +``` + +使用单数形式，会使用户产生该系统中只有一个 order 的困惑，用复数形式在逻辑上则顺畅很多。 + +```shell +curl -X GET "http://httpbin.org/orders"; +``` + +### 善用 HTTP 状态码 + +HTTP 标准定义个状态码，大致可以分为以下几类： + +|状态码|含义| +|:----|:----| +|2xx|成功，操作被成功接收并处理| +|3xx|重定向，需要进一步的操作以完成请求| +|4xx|客户端错误，请求包含语法错误或无法完成请求| +|5xx|服务器错误，服务器在处理请求的过程中发生了错误| Review Comment: I don’t know what‘s wrong with this table -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
![https://github.com/litesun.png"](https://github.com/litesun.png"){kind=link}
