0
# Nacos API
1

2
Nacos API is a comprehensive Java library that provides interfaces and common classes for dynamic service discovery, configuration management, and service management in cloud native applications and microservices. This package serves as the foundational layer for interacting with Nacos services through well-defined interfaces.
3

4
## Package Information
5

6
- **Package Name**: nacos-api
7
- **Package Type**: maven
8
- **Group ID**: com.alibaba.nacos
9
- **Language**: Java
10
- **Version**: 3.0.2
11
- **License**: Apache-2.0
12
- **Installation**: 
13

14
```xml
15
<dependency>
16
    <groupId>com.alibaba.nacos</groupId>
17
    <artifactId>nacos-api</artifactId>
18
    <version>3.0.2</version>
19
</dependency>
20
```
21

22
For Gradle:
23
```gradle
24
implementation 'com.alibaba.nacos:nacos-api:3.0.2'
25
```
26

27
## Core Imports
28

29
```java
30
import com.alibaba.nacos.api.NacosFactory;
31
import com.alibaba.nacos.api.PropertyKeyConst;
32
import com.alibaba.nacos.api.config.ConfigService;
33
import com.alibaba.nacos.api.naming.NamingService;
34
import com.alibaba.nacos.api.lock.LockService;
35
import com.alibaba.nacos.api.exception.NacosException;
36
```
37

38
## Basic Usage
39

40
```java
41
import com.alibaba.nacos.api.NacosFactory;
42
import com.alibaba.nacos.api.PropertyKeyConst;
43
import com.alibaba.nacos.api.config.ConfigService;
44
import com.alibaba.nacos.api.naming.NamingService;
45
import com.alibaba.nacos.api.naming.pojo.Instance;
46
import java.util.Properties;
47

48
// Initialize Nacos services
49
Properties properties = new Properties();
50
properties.setProperty(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
51
properties.setProperty(PropertyKeyConst.NAMESPACE, "public");
52

53
// Configuration management
54
ConfigService configService = NacosFactory.createConfigService(properties);
55
String config = configService.getConfig("myapp.properties", "DEFAULT_GROUP", 3000);
56
boolean published = configService.publishConfig("myapp.properties", "DEFAULT_GROUP", "key=value");
57

58
// Service discovery and registration
59
NamingService namingService = NacosFactory.createNamingService(properties);
60
namingService.registerInstance("my-service", "127.0.0.1", 8080);
61
List<Instance> instances = namingService.getAllInstances("my-service");
62

63
// Distributed locking
64
LockService lockService = NacosFactory.createLockService(properties);
65
LockInstance lock = new LockInstance();
66
lock.setLockName("my-distributed-lock");
67
boolean acquired = lockService.lock(lock);
68
```
69

70
## Architecture
71

72
The Nacos API is built around several key architectural components:
73

74
- **Factory Pattern**: `NacosFactory` provides centralized creation of all service instances
75
- **Service Interfaces**: Clean separation between `ConfigService`, `NamingService`, and `LockService`
76
- **Event-Driven Model**: Comprehensive listener system for configuration changes and service discovery events
77
- **Remote Communication**: Built-in gRPC and HTTP support for client-server communication
78
- **Health Checking**: Pluggable health check mechanisms (HTTP, TCP, MySQL)
79
- **Multi-tenancy**: Namespace support for resource isolation
80
- **Exception Handling**: Structured exception hierarchy with specific error codes
81

82
## Capabilities
83

84
### Core API and Factories
85

86
Central factory classes and property constants for creating and configuring Nacos services. Essential for initializing any Nacos functionality.
87

88
```java { .api }
89
class NacosFactory {
90
    static ConfigService createConfigService(Properties properties) throws NacosException;
91
    static ConfigService createConfigService(String serverAddr) throws NacosException;
92
    static NamingService createNamingService(String serverAddr) throws NacosException;
93
    static NamingService createNamingService(Properties properties) throws NacosException;
94
    static LockService createLockService(Properties properties) throws NacosException;
95
}
96

97
class PropertyKeyConst {
98
    static final String SERVER_ADDR = "serverAddr";
99
    static final String NAMESPACE = "namespace";
100
    static final String USERNAME = "username";
101
    static final String PASSWORD = "password";
102
    static final String ACCESS_KEY = "accessKey";
103
    static final String SECRET_KEY = "secretKey";
104
    static final String CONTEXT_PATH = "contextPath";
105
    static final String CLUSTER_NAME = "clusterName";
106
}
107
```
108

109
[Core API and Factory Classes](./core-api.md)
110

111
### Configuration Management
112

113
Dynamic configuration management with real-time updates, listeners, and fuzzy watching capabilities. Perfect for application settings, feature flags, and environment-specific configurations.
114

115
```java { .api }
116
interface ConfigService {
117
    String getConfig(String dataId, String group, long timeoutMs) throws NacosException;
118
    String getConfigAndSignListener(String dataId, String group, long timeoutMs, Listener listener) throws NacosException;
119
    boolean publishConfig(String dataId, String group, String content) throws NacosException;
120
    boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;
121
    boolean removeConfig(String dataId, String group) throws NacosException;
122
    void addListener(String dataId, String group, Listener listener) throws NacosException;
123
    void removeListener(String dataId, String group, Listener listener);
124
    void fuzzyWatch(String groupNamePattern, FuzzyWatchEventWatcher watcher) throws NacosException;
125
    void shutDown() throws NacosException;
126
}
127

128
interface Listener {
129
    Executor getExecutor();
130
    void receiveConfigInfo(String configInfo);
131
}
132
```
133

134
[Configuration Management](./configuration.md)
135

136
### Service Discovery and Naming
137

138
Service registration, discovery, and health monitoring with event-driven updates. Essential for microservices architectures and load balancing.
139

140
```java { .api }
141
interface NamingService {
142
    void registerInstance(String serviceName, String ip, int port) throws NacosException;
143
    void registerInstance(String serviceName, String groupName, String ip, int port) throws NacosException;
144
    void registerInstance(String serviceName, Instance instance) throws NacosException;
145
    void deregisterInstance(String serviceName, String ip, int port) throws NacosException;
146
    List<Instance> getAllInstances(String serviceName) throws NacosException;
147
    List<Instance> getAllInstances(String serviceName, String groupName) throws NacosException;
148
    List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;
149
    Instance selectOneHealthyInstance(String serviceName) throws NacosException;
150
    void subscribe(String serviceName, EventListener listener) throws NacosException;
151
    void unsubscribe(String serviceName, EventListener listener) throws NacosException;
152
    void fuzzyWatch(String groupNamePattern, FuzzyWatchEventWatcher listener) throws NacosException;
153
    void shutDown() throws NacosException;
154
}
155

156
class Instance {
157
    String instanceId;
158
    String ip;
159
    int port;
160
    double weight;
161
    boolean healthy;
162
    boolean enabled;
163
    boolean ephemeral;
164
    String clusterName;
165
    String serviceName;
166
    Map<String, String> metadata;
167
}
168
```
169

170
[Service Discovery and Naming](./naming.md)
171

172
### Remote Communication
173

174
Low-level remote communication infrastructure including gRPC support, request/response handling, and connection management.
175

176
```java { .api }
177
abstract class Request implements Payload {
178
    void putHeader(String key, String value);
179
    void putAllHeader(Map<String, String> headers);
180
    String getHeader(String key);
181
    String getRequestId();
182
    void setRequestId(String requestId);
183
}
184

185
abstract class Response implements Payload {
186
    boolean isSuccess();
187
    int getResultCode();
188
    void setResultCode(int resultCode);
189
    int getErrorCode();
190
    void setErrorCode(int errorCode);
191
    String getMessage();
192
    void setMessage(String message);
193
}
194

195
interface RequestCallBack<T extends Response> {
196
    void onResponse(T response);
197
    void onException(Throwable e);
198
}
199
```
200

201
[Remote Communication](./remote.md)
202

203
### AI and Model Context Protocol (MCP) Integration
204

205
Advanced AI integration capabilities including Model Context Protocol (MCP) server management, tool specifications, and service discovery integration for AI agents.
206

207
```java { .api }
208
class McpTool {
209
    String name;
210
    String description;
211
    Map<String, Object> inputSchema;
212
    
213
    String getName();
214
    void setName(String name);
215
    String getDescription();
216
    void setDescription(String description);
217
    Map<String, Object> getInputSchema();
218
    void setInputSchema(Map<String, Object> inputSchema);
219
}
220

221
class McpServiceRef {
222
    String namespaceId;
223
    String groupName;
224
    String serviceName;
225
    
226
    String getNamespaceId();
227
    void setNamespaceId(String namespaceId);
228
    String getGroupName();
229
    void setGroupName(String groupName);
230
    String getServiceName();
231
    void setServiceName(String serviceName);
232
}
233

234
class AiConstants.Mcp {
235
    static final String MCP_DEFAULT_NAMESPACE = "public";
236
    static final String MCP_PROTOCOL_STDIO = "stdio";
237
    static final String MCP_PROTOCOL_SSE = "mcp-sse";
238
    static final String MCP_PROTOCOL_HTTP = "http";
239
    static final String MCP_PROTOCOL_DUBBO = "dubbo";
240
}
241
```
242

243
[AI and Model Context Protocol Integration](./ai-mcp.md)
244

245
### Exception Handling
246

247
Comprehensive exception hierarchy with specific error codes and handling patterns for robust error management.
248

249
```java { .api }
250
class NacosException extends Exception {
251
    NacosException();
252
    NacosException(int errCode, String errMsg);
253
    NacosException(int errCode, Throwable throwable);
254
    NacosException(int errCode, String errMsg, Throwable throwable);
255
    
256
    int getErrCode();
257
    String getErrMsg();
258
    void setErrCode(int errCode);
259
    void setErrMsg(String errMsg);
260
    
261
    // Client error codes
262
    static final int CLIENT_INVALID_PARAM = -400;
263
    static final int CLIENT_DISCONNECT = -401;
264
    static final int CLIENT_OVER_THRESHOLD = -503;
265
    
266
    // Server error codes
267
    static final int INVALID_PARAM = 400;
268
    static final int NO_RIGHT = 403;
269
    static final int NOT_FOUND = 404;
270
    static final int CONFLICT = 409;
271
    static final int SERVER_ERROR = 500;
272
    static final int BAD_GATEWAY = 502;
273
    static final int OVER_THRESHOLD = 503;
274
}
275
```
276

277
[Exception Handling](./exceptions.md)
278

279
## Common Constants
280

281
```java { .api }
282
class Constants {
283
    static final String CLIENT_VERSION = "3.0.0";
284
    static final String DEFAULT_GROUP = "DEFAULT_GROUP";
285
    static final String DEFAULT_CLUSTER_NAME = "DEFAULT";
286
    static final String DEFAULT_NAMESPACE_ID = "public";
287
    static final long DEFAULT_HEART_BEAT_TIMEOUT = 15000;
288
    static final long DEFAULT_HEART_BEAT_INTERVAL = 5000;
289
    static final int POLLING_INTERVAL_TIME = 15;
290
    static final int CONFIG_LONG_POLL_TIMEOUT = 30000;
291
    static final int MAX_RETRY = 3;
292
}
293

294
enum ConfigType {
295
    UNSET, TEXT, JSON, XML, YAML, HTML, PROPERTIES;
296
}
297

298
enum PropertyChangeType {
299
    ADDED, MODIFIED, DELETED;
300
}
301
```
302

303
## Utility Classes
304

305
```java { .api }
306
class StringUtils {
307
    static boolean isEmpty(String str);
308
    static boolean isNotEmpty(String str);
309
    static boolean isBlank(String str);
310
    static boolean isNotBlank(String str);
311
}
312

313
class NamingUtils {
314
    static boolean isNumber(String str);
315
    static String getGroupedName(String serviceName, String groupName);
316
    static String[] getGroupAndServiceName(String serviceName);
317
}
318
```