Documentation

Open API Guide

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 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.
  • dataId : Configuration ID
  • group : Configuration group
  • contentMD5 : The MD5 value of the configuration
  • tenant : Tenant information. It corresponds to the Namespace field in Nacos (not must)
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 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 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