RESTful API 是什么及其最佳实践

本文将深入探讨RESTful API的概念、核心约束条件、设计最佳实践，以及Apache APISIX如何助力RESTful API的实现。通过本文，您将全面了解RESTful API及其在现代API架构中的重要性。

RESTful API 的定义与核心约束

RESTful API是一种建筑风格，用于设计网络应用程序的API。REST代表“表现层状态转移”，由Roy Fielding在其2000年的博士论文中定义。RESTful API必须遵循六个约束条件：

1. 客户端-服务器架构

通过分离用户界面和数据存储，提高了跨多个平台的用户界面的可移植性，并通过简化服务器组件提高了可扩展性。

2. 无状态

每个请求从客户端到服务器必须包含所有必要的信息，服务器不存储任何会话信息。

3. 可缓存

响应被标记为可缓存或不可缓存。这减少了不必要的带宽使用和服务器负载。

4. 分层系统

通过限制组件行为允许架构由分层层组成，降低了整个系统的复杂性并促进了底层独立性。

5. 按需代码（可选）

允许通过下载和执行小程序或脚本形式的代码来扩展客户端功能。

6. 统一接口

包括资源识别、资源操作、自描述消息和超媒体作为应用状态的引擎。

RESTful API

RESTful API 设计最佳实践

设计RESTful API时，需要遵循一些最佳实践，以确保API的可读性、可维护性和一致性。

路径名称避免动词

使用HTTP方法表达资源操作行为，而不是将行为动词定义到路径中。

curl -X GET http://httpbin.org/orders



curl -X GET "http://httpbin.org/getOrders"

URI 使用复数形式

使用复数形式可以更清晰地表达资源的集合。

curl -X GET "http://httpbin.org/orders"



curl -X GET "http://httpbin.org/order"

善用 HTTP 状态码

使用标准状态码可以帮助快速识别问题。

版本管理

随着业务需求的变更，已经上线的API需要对应调整。引入API版本管理可以保证历史API正常使用，同时迭代新的API以满足新的业务需求。

curl  http://httpbin.org/v1/orders



curl  http://httpbin.org/v2/orders

Apache APISIX 如何助力RESTful API

Apache APISIX是一个动态、实时、高性能的API网关，可以在任何RESTful API服务上运行，并使用插件来添加新的服务和扩展其功能。

分层系统：支持业务逻辑和安全逻辑的分割

APISIX可以在业务服务器前面加一层认证逻辑，保护上游服务，实现业务逻辑和安全逻辑的高效解耦。

APISIX 的作用

Layered system：多负载均衡协议支持

APISIX作为API网关，可以设立在客户端和服务端之间，完成不同的负载需求。支持的负载均衡算法包括roundrobin、chash、ewma和least_conn。

统一接口：使历史API更加RESTful

对于已经存在很久的历史API，如果没有很好地遵循RESTful API准则，可以在不改造原有API逻辑的情况下，通过APISIX重新封装新的API以满足不同的业务场景。

使用 proxy-rewrite 改写客户端请求

例如，历史版本API有 /getOrder 接口，可以通过 proxy-rewrite 插件将API请求代理到历史API上。

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

{

    "methods": ["GET"],

    "uri": "/orders",

    "plugins": {

        "proxy-rewrite": {

            "uri": "/getOrder",

            "scheme": "http",

        }

    },

    "upstream": {

        "type": "roundrobin",

        "nodes": {

            "127.0.0.1:80": 1

        }

    }

}'

使用 response-rewrite 插件改写服务端响应

当历史API存在响应状态码不规范时，可以通过 response-rewrite 代理response响应从而达到修改响应状态码的目的。

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '

{

    "methods": ["GET"],

    "uri": "/orders",

    "plugins": {

        "response-rewrite": {

            "status_code": 201,

            "body": "{"code":"ok","message":"new json body"}",

            "vars":[

                [ "status", "==", 200 ]

            ]

        }

    },

    "upstream": {

        "type": "roundrobin",

        "nodes": {

            "127.0.0.1:80": 1

        }

    }

}'