- Open API Guide
- Configuration Management
- Get configurations
- Listen for configurations
- Publish configuration
- Delete configuration
- Service Discovery
- Register instance
- Deregister instance
- Modify instance
- Query instances
- Query instance detail
- Send instance beat
- Create service
- Delete service
- Update service
- Query service
- Query service list
- Query system switches
- Update system switch
- Query system metrics
- Query server list
- Query the leader of current cluster
- Update instance health status
Open API Guide
- Configuration Management
-
Service Discovery
- Register instance
- Deregister instance
- Modify instance
- Query instances
- Query instance detail
- Send instance beat
- Create service
- Delete service
- Update service
- Query service
- Query service list
- Query system switches
- Update system switch
- Query system metrics
- Query server list
- Query the leader of current cluster
- Update instance health status
Configuration Management
Get configurations
Description
This API is used to get configurations in Nacos.
Request type
GET
Request URL
/nacos/v1/cs/configs
Request parameters
Name | Type | Required | Description |
---|---|---|---|
tenant | string | No | Tenant information. It corresponds to the Namespace ID field in Nacos. |
dataId | string | Yes | Configuration ID |
group | string | Yes | Configuration group |
Return parameters
Parameter type | Description |
---|---|
String | Configuration value |
Error codes
Error code | Description | Meaning |
---|---|---|
400 | Bad Request | Syntax error in the client request |
403 | Forbidden | No permission |
404 | Not Found | Not found resource |
500 | Internal Server Error | Internal server error |
200 | OK | Normal |
Example
-
Request example
http:serverIp:8848/nacos/v1/cs/configs?dataId=dataIdparam&group=groupParam&tenant=tenantParam
-
Return example
contentTest
Listen for configurations
Description
This API is used to listen for configurations in Nacos to capture configuration changes. In case of any configuration changes, you can use the Get Configurations API to obtain the latest value of the configuration and dynamically refresh the local cache.
A listener is registered using an asynchronous servlet. The nature of registering a listener is to compare the configuration value and the MD5 value of it with that of the backend. If the values differ, the inconsistent configuration is returned immediately. Otherwise, an empty string is returned after 30 seconds.
Request type
POST
Request URL
/nacos/v1/cs/configs/listener
Request parameters
Name | Type | Required | Description |
Listening-Configs | string | No |
A request to listen for data packets.
Format : dataId^group^2contentMD5^tenant^1 or dataId^group^2contentMD5^1.
|
Listening-Configs | string | Yes | A request to listen for data packets. |
tenant | string | Yes | A packet field indicating tenant information. It corresponds to the Namespace field in Nacos. |
dataId | string | Yes | A packet field indicating the configuration ID. |
group | string | Yes | A packet field indicating the configuration group. |
contentMD5 | string | Yes | A packet field indicating the MD5 value of the configuration. |
Header parameters
Name | Type | Required | Description |
---|---|---|---|
Long-Pulling-Timeout | string | Yes | The timeout for long polling is 30s. Enter 30,000 here. |
Parameter description
- A delimiter to separate fields within a configuration: ^2 = Character.toString((char) 2
- A delimiter to separate configurations: ^1 = Character.toString((char) 1)
- contentMD5: MD5(content). This is an empty string because the first local cache is empty.
Return parameters
Parameter type | Description |
---|---|
String | Configuration value |
Error codes
Error code | Description | Meaning |
---|---|---|
400 | Bad Request | Syntax error in the client request |
403 | Forbidden | No permission |
404 | Not Found | Client error, not found |
500 | Internal Server Error | Internal server error |
200 | OK | Normal |
Example
- Request example
http://serverIp:8848/nacos/v1/cs/configs/listener
POST request body data:
Listening-Configs=dataId^2group^2contentMD5^2tenant^1
- Return example
In case of any configuration changes,
dataId^2group^2tenant^1
Otherwise, an empty string is returned.
Publish configuration
Description
It publishes configurations in Nacos.
Request Type
POST
Request URL
/nacos/v1/cs/configs
Request parameters
Name | Type | Required | Description |
---|---|---|---|
tenant | String | No | The tenant, corresponding to the namespace ID field of Nacos |
dataId | String | Yes | Configuration ID |
group | String | Yes | Configuration group |
content | String | Yes | Configuration content |
type | String | No | Configuration type |
Response parameters
Parametertype | Description |
---|---|
boolean | If the publishing is successful |
Error code
Error code | Description | Meaning |
---|---|---|
400 | Bad Request | Syntax error in client request |
403 | Forbidden | No permission |
404 | Not Found | Not found resource |
500 | Internal Server Error | Internal server error |
200 | OK | Normal |
Example
Request example
http:serverIp:8848/nacos/v1/cs/configs
http body:
dataId=dataIdparam&group=groupParam&tenant=tenantParam&content=contentParam&type=typeParam
Response example
true
Delete configuration
Description
It deletes configurations in Nacos.
Request Type
DELETE
Request URL
/nacos/v1/cs/configs
Request parameters
Name | Type | Required | Description |
---|---|---|---|
tenant | String | No | The tenant, corresponding to the namespace ID field of Nacos |
dataId | String | Yes | Configuration ID |
group | String | Yes | Configuration group |
Response parameters
Parameter type | Description |
---|---|
boolean | If the deletion is successful |
Error code
Error code | Description | Meaning |
---|---|---|
400 | Bad Request | Syntax error in client request |
403 | Forbidden | No permission |
404 | Not Found | Not found resource |
500 | Internal Server Error | Internal server error |
200 | OK | Normal |
Example
Request example
http:serverIp:8848/nacos/cs/configs?dataId=dataIdparam&group=groupParam
Response example
true
Service Discovery
Register instance
Description
Register an instance to service.
Request Type
POST
Request Path
/nacos/v1/ns/instance
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
ip | String | yes | IP of instance |
port | int | yes | Port of instance |
namespaceId | String | no | ID of namespace |
weight | double | no | Weight |
enabled | boolean | no | enabled or not |
healthy | boolean | no | healthy or not |
metadata | String | no | extended information |
clusterName | String | no | cluster name |
serviceName | String | yes | service name |
groupName | String | no | group name |
ephemeral | boolean | no | if instance is ephemeral |
Request Example
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1''
Response Example
ok
Deregister instance
Description
Delete instance from service.
Request Type
DELETE
Request Path
/nacos/v1/ns/instance
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | Service name |
groupName | String | no | group name |
ephemeral | boolean | no | if instance is ephemeral |
ip | String | yes | IP of instance |
port | int | yes | Port of instance |
clusterName | String | no | Cluster name |
namespaceId | String | no | ID of namespace |
Request Example
curl -X DELETE 127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1
Response Example
ok
Modify instance
Description
Modify an instance of service.
Request Type
PUT
Request Path
/nacos/v1/ns/instance
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | Service name |
groupName | String | no | group name |
ephemeral | boolean | no | if instance is ephemeral |
ip | String | yes | IP of instance |
port | int | yes | Port of instance |
clusterName | String | no | Cluster name |
namespaceId | String | no | ID of namespace |
weight | double | no | Weight |
enabled | boolean | no | If enabled |
metadata | JSON | no | Extended information |
Request Example
curl -X PUT 127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1&weight=8&metadata={}
Response Example
ok
Query instances
Description
Query instance list of service.
Request Type
GET
Request Path
/nacos/v1/ns/instance/list
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | Service name |
groupName | String | no | group name |
namespaceId | String | no | ID of namespace |
clusters | String, splited by comma | no | Cluster name |
healthyOnly | boolean | no, default value is false | Return healthy instance or not |
Request Example
curl -X GET 127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1
Response Example
{
"dom": "nacos.test.1",
"cacheMillis": 1000,
"useSpecifiedURL": false,
"hosts": [{
"valid": true,
"marked": false,
"instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.1",
"port": 8888,
"ip": "10.10.10.10",
"weight": 1.0,
"metadata": {}
}],
"checksum": "3bbcf6dd1175203a8afdade0e77a27cd1528787794594",
"lastRefTime": 1528787794594,
"env": "",
"clusters": ""
}
Query instance detail
Description
Query instance details of service.
Request Type
GET
Request Path
/nacos/v1/ns/instance
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
namespaceId | String | no | ID of namespace |
serviceName | String | yes | Service name |
groupName | String | no | group name |
ephemeral | boolean | no | if instance is ephemeral |
ip | String | yes | IP of instance |
port | String | yes | Port of instance |
cluster | String | no | Cluster name |
Request Example
curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.2&ip=10.10.10.10&port=8888&cluster=DEFAULT'
Response Example
{
"metadata": {},
"instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.2",
"port": 8888,
"service": "nacos.test.2",
"healthy": false,
"ip": "10.10.10.10",
"clusterName": "DEFAULT",
"weight": 1.0
}
Send instance beat
Description
Send instance beat
Request Type
PUT
Request Path
/nacos/v1/ns/instance/beat
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
namespaceId | String | no | ID of namespace |
serviceName | String | yes | service name |
groupName | String | no | group name |
beat | String | yes | beat content |
Request Example
curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=nacos.test.2&beat=%7b%22cluster%22%3a%22c1%22%2c%22ip%22%3a%22127.0.0.1%22%2c%22metadata%22%3a%7b%7d%2c%22port%22%3a8080%2c%22scheduled%22%3atrue%2c%22serviceName%22%3a%22jinhan0Fx4s.173TL.net%22%2c%22weight%22%3a1%7d'
Response Example
ok
Create service
Description
Create service
Request Type
POST
Request Path
/nacos/v1/ns/service
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | service name |
groupName | String | no | group name |
namespaceId | String | no | namespace id |
protectThreshold | float | no | set value from 0 to 1, default 0 |
metadata | String | no | metadata of service |
selector | JSON | no | visit strategy |
Request Example
curl -X POST '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'
Response Example
ok
Delete service
Description
Delete a service, only permitted when instance count is 0.
Request Type
DELETE
Request Path
/nacos/v1/ns/service
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | service name |
groupName | String | no | group name |
namespaceId | String | no | namespace id |
Request Example
curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'
Response Example
ok
Update service
Description
Update a service
Request Type
PUT
Request Path
/nacos/v1/ns/service
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | service name |
groupName | String | no | group name |
namespaceId | String | no | namespace id |
protectThreshold | float | no | set value from 0 to 1, default 0 |
metadata | String | no | metadata of service |
selector | JSON | no | visit strategy |
Request Example
curl -X PUT '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'
Response Example
ok
Query service
Description
Query a service
Request Type
GET
Request Path
/nacos/v1/ns/service
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | service name |
groupName | String | no | group name |
namespaceId | String | no | namespace id |
Request Example
curl -X GET '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'
Response Example
{
metadata: { },
groupName: "DEFAULT_GROUP",
namespaceId: "public",
name: "nacos.test.2",
selector: {
type: "none"
},
protectThreshold: 0,
clusters: [
{
healthChecker: {
type: "TCP"
},
metadata: { },
name: "c1"
}
]
}
Query service list
Description
Query service list
Request Type
GET
Request Path
/nacos/v1/ns/service/list
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
pageNo | int | yes | current page number |
pageSize | int | yes | page size |
groupName | String | no | group name |
namespaceId | String | no | namespace id |
Request Example
curl -X GET '127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=2'
Response Example
{
"count":148,
"doms": [
"nacos.test.1",
"nacos.test.2"
]
}
Query system switches
Description
Query system switches
Request Type
GET
Request Path
/nacos/v1/ns/operator/switches
Request Parameters
Request Example
curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/switches'
Response Example
{
name: "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
masters: null,
adWeightMap: { },
defaultPushCacheMillis: 10000,
clientBeatInterval: 5000,
defaultCacheMillis: 3000,
distroThreshold: 0.7,
healthCheckEnabled: true,
distroEnabled: true,
enableStandalone: true,
pushEnabled: true,
checkTimes: 3,
httpHealthParams: {
max: 5000,
min: 500,
factor: 0.85
},
tcpHealthParams: {
max: 5000,
min: 1000,
factor: 0.75
},
mysqlHealthParams: {
max: 3000,
min: 2000,
factor: 0.65
},
incrementalList: [ ],
serverStatusSynchronizationPeriodMillis: 15000,
serviceStatusSynchronizationPeriodMillis: 5000,
disableAddIP: false,
sendBeatOnly: false,
limitedUrlMap: { },
distroServerExpiredMillis: 30000,
pushGoVersion: "0.1.0",
pushJavaVersion: "0.1.0",
pushPythonVersion: "0.4.3",
pushCVersion: "1.0.12",
enableAuthentication: false,
overriddenServerStatus: "UP",
defaultInstanceEphemeral: true,
healthCheckWhiteList: [ ],
checksum: null
}
Update system switch
Description
Update system switch
Request Type
PUT
Request Path
/nacos/v1/ns/operator/switches
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
entry | String | yes | switch name |
value | String | yes | switch value |
debug | boolean | no | if affect the local server, true means yes, false means no, default true |
Request Example
curl -X PUT '127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&value=false&debug=true'
Response Example
ok
Query system metrics
Description
Query system metrics
Request Type
GET
Request Path
/nacos/v1/ns/operator/metrics
Request Parameters
Request Example
curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/metrics'
Response Example
{
serviceCount: 336,
load: 0.09,
mem: 0.46210432,
responsibleServiceCount: 98,
instanceCount: 4,
cpu: 0.010242796,
status: "UP",
responsibleInstanceCount: 0
}
Query server list
Description
Query server list
Request Type
GET
Request Path
/nacos/v1/ns/operator/servers
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
healthy | boolean | no | if return healthy servers only |
Request Example
curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/servers'
Response Example
{
servers: [
{
ip: "1.1.1.1",
servePort: 8848,
site: "unknown",
weight: 1,
adWeight: 0,
alive: false,
lastRefTime: 0,
lastRefTimeStr: null,
key: "1.1.1.1:8848"
},
{
ip: "1.1.1.2",
servePort: 8848,
site: "unknown",
weight: 1,
adWeight: 0,
alive: false,
lastRefTime: 0,
lastRefTimeStr: null,
key: "1.1.1.2:8848"
},
{
ip: "1.1.1.3",
servePort: 8848,
site: "unknown",
weight: 1,
adWeight: 0,
alive: false,
lastRefTime: 0,
lastRefTimeStr: null,
key: "1.1.1.3:8848"
}
]
}
Query the leader of current cluster
Description
Query the leader of current cluster
Request Type
GET
Request Path
/nacos/v1/ns/raft/leader
Request Parameters
Request Example
curl -X GET '127.0.0.1:8848/nacos/v1/ns/raft/leader'
Response Example
{
leader: "{"heartbeatDueMs":2500,"ip":"1.1.1.1:8848","leaderDueMs":12853,"state":"LEADER","term":54202,"voteFor":"1.1.1.1:8848"}"
}
Update instance health status
Description
Update instance health status, only works when the cluster health checker is set to NONE.
Request Type
PUT
Request Path
/nacos/v1/ns/health/instance
Request Parameters
Name | Type | Required | Description |
---|---|---|---|
serviceName | String | yes | service name |
groupName | String | no | group name |
namespaceId | String | no | namespace id |
clusterName | String | no | cluster name |
ip | String | yes | ip of instance |
port | int | yes | port of instance |
healthy | boolean | yes | if healthy |
Request Example
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/health/instance?port=8848&healthy=true&ip=11.11.11.11&serviceName=nacos.test.3&namespaceId=n1''
Response Example
ok