Nacos Open API Overview

Nacos Open API Overview

Nacos Open API 概览

1. Nacos Open API 分类

Nacos 3.0 为了匹配不同使用场景，同时也为了能够让不同类型的API实施不同的安全认证机制，将Open API进行了多维度的分类：

• Client Open API : 用于客户端和应用程序的OpenAPI，客户端和应用程序通过OpenAPI与Nacos进行数据交互，主要为微服务类型、普通应用程序及AI Agent应用提供精确的数据数据访问能力，这类应用的主要特点是对于需要访问的资源有着较高的确定性，同时对此类API的性能及响应速度要求较高。
• Admin Open API : 用于运维人员和管理平面的OpenAPI，管理平面通过OpenAPI与Nacos进行数据交互，主要为运维人员、监控人员、审计人员及各种运维工具提供大范围的数据检索访问能力，这类应用或调用者的主要特点是可能需要对不确定性或大访问的数据进行检索，但调用次数及频率相对较低，并且对响应时间的要求也相对较低。
• Console Open API : 用于控制台的OpenAPI，控制台通过OpenAPI与Nacos进行数据交互，主要为控制台提供数据检索及数据修改的能力，此类应用或调用者的主要特点是需要与Admin Open API相似，但更关注数据类型的API，对控制Nacos本身的的要求相对较低。

2. Nacos Open API 访问协议

Nacos 3.0 主要支持两种访问协议， 分别为 gRPC 和 HTTP 1.1（下文简称HTTP）。根据不同的Nacos Open API分类的特点，分别使用不同的协议进行。

• Client Open API : 主要使用 gRPC协议进行访问，相比与HTTP 1.1， gRPC基于性能更高的 HTTP 2协议进行构建， 同时使用了多语言通用的protobuf序列化能力，能够快速构建多种编程语言的通信协议客户端，更能满足Client Open API 对于高吞吐及响应速度的要求。考虑到部分编程语言可能未提供稳定的gRPC能力，Client Open API 也提供HTTP 1.1协议的部分接口，允许开发者选择适合自己的编程语言进行开发。
• Admin Open API 和 Console Open API : 使用HTTP 1.1协议进行访问，允许开发者使用任何编程语言进行开发，同时对浏览器UI等有更好的兼容性。

3. Nacos Open API 定义规范

3.1. gRPC API 统一返回体格式

3.0版本的gRPC Open API，所有接口请求的响应均通过proto文件中的Payload承载，必然包含字段如下

3.2. HTTP API 统一返回体格式

3.0版本HTTP Open API，所有接口请求的响应均为json类型的返回体，返回体具有相同的格式

{
  "code": 0,
  "message": "success",
  "data": {}
}

返回体中各字段的含义如下表所示

由于执行成功的情况下code字段与message字段相同，后续在介绍接口的返回结果时，只介绍返回数据的data字段

3.3. API 错误码汇总

API接口返回体中的错误码及对应提示信息汇总见下表