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

NameTypeRequiredDescription
tenantstringNoTenant information. It corresponds to the Namespace ID field in Nacos.
dataIdstringYesConfiguration ID
groupstringYesConfiguration group

Return parameters

Parameter typeDescription
StringConfiguration value

Error codes

Error codeDescriptionMeaning
400Bad RequestSyntax error in the client request
403ForbiddenNo permission
404Not FoundNot found resource
500Internal Server ErrorInternal server error
200OKNormal

Example

  • Request example
    1. http:serverIp:8848/nacos/v1/cs/configs?dataId=dataIdparam&group=groupParam&tenant=tenantParam
  • Return example
    1. 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

NameTypeRequiredDescription
Long-Pulling-TimeoutstringYesThe 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 typeDescription
StringConfiguration value

Error codes

Error codeDescriptionMeaning
400Bad RequestSyntax error in the client request
403ForbiddenNo permission
404Not FoundClient error, not found
500Internal Server ErrorInternal server error
200OKNormal

Example

  • Request example
  1. http://serverIp:8848/nacos/v1/cs/configs/listener
  2. POST request body data:
  3. Listening-Configs=dataId^2group^2contentMD5^2tenant^1
  • Return example
  1. In case of any configuration changes,
  2. dataId^2group^2tenant^1
  3. 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

NameTypeRequiredDescription
tenantStringNoThe tenant, corresponding to the namespace ID field of Nacos
dataIdStringYesConfiguration ID
groupStringYesConfiguration group
contentStringYesConfiguration content
typeStringNoConfiguration type

Response parameters

ParametertypeDescription
booleanIf the publishing is successful

Error code

Error codeDescriptionMeaning
400Bad RequestSyntax error in client request
403ForbiddenNo permission
404Not FoundNot found resource
500Internal Server ErrorInternal server error
200OKNormal

Example

Request example

  1. http:serverIp:8848/nacos/v1/cs/configs
  2. http body
  3. dataId=dataIdparam&group=groupParam&tenant=tenantParam&content=contentParam&type=typeParam

Response example

  1. true

Delete configuration

Description

It deletes configurations in Nacos.

Request Type

DELETE

Request URL

/nacos/v1/cs/configs

Request parameters

NameTypeRequiredDescription
tenantStringNoThe tenant, corresponding to the namespace ID field of Nacos
dataIdStringYesConfiguration ID
groupStringYesConfiguration group

Response parameters

Parameter typeDescription
booleanIf the deletion is successful

Error code

Error codeDescriptionMeaning
400Bad RequestSyntax error in client request
403ForbiddenNo permission
404Not FoundNot found resource
500Internal Server ErrorInternal server error
200OKNormal

Example

Request example

  1. http:serverIp:8848/nacos/cs/configs?dataId=dataIdparam&group=groupParam

Response example

  1. true

Service Discovery

Register instance

Description

Register an instance to service.

Request Type

POST

Request Path

  1. /nacos/v1/ns/instance

Request Parameters

NameTypeRequiredDescription
ipStringyesIP of instance
portintyesPort of instance
namespaceIdStringnoID of namespace
weightdoublenoWeight
enabledbooleannoenabled or not
healthybooleannohealthy or not
metadataStringnoextended information
clusterNameStringnocluster name
serviceNameStringyesservice name
groupNameStringnogroup name
ephemeralbooleannoif instance is ephemeral

Request Example

  1. 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

  1. /nacos/v1/ns/instance

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesService name
groupNameStringnogroup name
ephemeralbooleannoif instance is ephemeral
ipStringyesIP of instance
portintyesPort of instance
clusterNameStringnoCluster name
namespaceIdStringnoID of namespace

Request Example

  1. 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

  1. /nacos/v1/ns/instance

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesService name
groupNameStringnogroup name
ephemeralbooleannoif instance is ephemeral
ipStringyesIP of instance
portintyesPort of instance
clusterNameStringnoCluster name
namespaceIdStringnoID of namespace
weightdoublenoWeight
enabledbooleannoIf enabled
metadataJSONnoExtended information

Request Example

  1. 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

  1. /nacos/v1/ns/instance/list

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesService name
groupNameStringnogroup name
namespaceIdStringnoID of namespace
clustersString, splited by commanoCluster name
healthyOnlybooleanno, default value is falseReturn healthy instance or not

Request Example

  1. curl -X GET 127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1

Response Example

  1. {
  2. "dom": "nacos.test.1",
  3. "cacheMillis": 1000,
  4. "useSpecifiedURL": false,
  5. "hosts": [{
  6. "valid": true,
  7. "marked": false,
  8. "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.1",
  9. "port": 8888,
  10. "ip": "10.10.10.10",
  11. "weight": 1.0,
  12. "metadata": {}
  13. }],
  14. "checksum": "3bbcf6dd1175203a8afdade0e77a27cd1528787794594",
  15. "lastRefTime": 1528787794594,
  16. "env": "",
  17. "clusters": ""
  18. }

Query instance detail

Description

Query instance details of service.

Request Type

GET

Request Path

  1. /nacos/v1/ns/instance

Request Parameters

NameTypeRequiredDescription
namespaceIdStringnoID of namespace
serviceNameStringyesService name
groupNameStringnogroup name
ephemeralbooleannoif instance is ephemeral
ipStringyesIP of instance
portStringyesPort of instance
clusterStringnoCluster name

Request Example

  1. 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

  1. {
  2. "metadata": {},
  3. "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.2",
  4. "port": 8888,
  5. "service": "nacos.test.2",
  6. "healthy": false,
  7. "ip": "10.10.10.10",
  8. "clusterName": "DEFAULT",
  9. "weight": 1.0
  10. }

Send instance beat

Description

Send instance beat

Request Type

PUT

Request Path

  1. /nacos/v1/ns/instance/beat

Request Parameters

NameTypeRequiredDescription
namespaceIdStringnoID of namespace
serviceNameStringyesservice name
groupNameStringnogroup name
beatStringyesbeat content

Request Example

  1. 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

  1. ok

Create service

Description

Create service

Request Type

POST

Request Path

  1. /nacos/v1/ns/service

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesservice name
groupNameStringnogroup name
namespaceIdStringnonamespace id
protectThresholdfloatnoset value from 0 to 1, default 0
metadataStringnometadata of service
selectorJSONnovisit strategy

Request Example

  1. curl -X POST '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

Response Example

  1. ok

Delete service

Description

Delete a service, only permitted when instance count is 0.

Request Type

DELETE

Request Path

  1. /nacos/v1/ns/service

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesservice name
groupNameStringnogroup name
namespaceIdStringnonamespace id

Request Example

  1. curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

Response Example

  1. ok

Update service

Description

Update a service

Request Type

PUT

Request Path

  1. /nacos/v1/ns/service

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesservice name
groupNameStringnogroup name
namespaceIdStringnonamespace id
protectThresholdfloatnoset value from 0 to 1, default 0
metadataStringnometadata of service
selectorJSONnovisit strategy

Request Example

  1. curl -X PUT '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

Response Example

  1. ok

Query service

Description

Query a service

Request Type

GET

Request Path

  1. /nacos/v1/ns/service

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesservice name
groupNameStringnogroup name
namespaceIdStringnonamespace id

Request Example

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

Response Example

  1. {
  2. metadata: { },
  3. groupName: "DEFAULT_GROUP",
  4. namespaceId: "public",
  5. name: "nacos.test.2",
  6. selector: {
  7. type: "none"
  8. },
  9. protectThreshold: 0,
  10. clusters: [
  11. {
  12. healthChecker: {
  13. type: "TCP"
  14. },
  15. metadata: { },
  16. name: "c1"
  17. }
  18. ]
  19. }

Query service list

Description

Query service list

Request Type

GET

Request Path

  1. /nacos/v1/ns/service/list

Request Parameters

NameTypeRequiredDescription
pageNointyescurrent page number
pageSizeintyespage size
groupNameStringnogroup name
namespaceIdStringnonamespace id

Request Example

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=2'

Response Example

  1. {
  2. "count":148,
  3. "doms": [
  4. "nacos.test.1",
  5. "nacos.test.2"
  6. ]
  7. }

Query system switches

Description

Query system switches

Request Type

GET

Request Path

  1. /nacos/v1/ns/operator/switches

Request Parameters

Request Example

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/switches'

Response Example

  1. {
  2. name: "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
  3. masters: null,
  4. adWeightMap: { },
  5. defaultPushCacheMillis: 10000,
  6. clientBeatInterval: 5000,
  7. defaultCacheMillis: 3000,
  8. distroThreshold: 0.7,
  9. healthCheckEnabled: true,
  10. distroEnabled: true,
  11. enableStandalone: true,
  12. pushEnabled: true,
  13. checkTimes: 3,
  14. httpHealthParams: {
  15. max: 5000,
  16. min: 500,
  17. factor: 0.85
  18. },
  19. tcpHealthParams: {
  20. max: 5000,
  21. min: 1000,
  22. factor: 0.75
  23. },
  24. mysqlHealthParams: {
  25. max: 3000,
  26. min: 2000,
  27. factor: 0.65
  28. },
  29. incrementalList: [ ],
  30. serverStatusSynchronizationPeriodMillis: 15000,
  31. serviceStatusSynchronizationPeriodMillis: 5000,
  32. disableAddIP: false,
  33. sendBeatOnly: false,
  34. limitedUrlMap: { },
  35. distroServerExpiredMillis: 30000,
  36. pushGoVersion: "0.1.0",
  37. pushJavaVersion: "0.1.0",
  38. pushPythonVersion: "0.4.3",
  39. pushCVersion: "1.0.12",
  40. enableAuthentication: false,
  41. overriddenServerStatus: "UP",
  42. defaultInstanceEphemeral: true,
  43. healthCheckWhiteList: [ ],
  44. checksum: null
  45. }

Update system switch

Description

Update system switch

Request Type

PUT

Request Path

  1. /nacos/v1/ns/operator/switches

Request Parameters

NameTypeRequiredDescription
entryStringyesswitch name
valueStringyesswitch value
debugbooleannoif affect the local server, true means yes, false means no, default true

Request Example

  1. curl -X PUT '127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&value=false&debug=true'

Response Example

  1. ok

Query system metrics

Description

Query system metrics

Request Type

GET

Request Path

  1. /nacos/v1/ns/operator/metrics

Request Parameters

Request Example

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/metrics'

Response Example

  1. {
  2. serviceCount: 336,
  3. load: 0.09,
  4. mem: 0.46210432,
  5. responsibleServiceCount: 98,
  6. instanceCount: 4,
  7. cpu: 0.010242796,
  8. status: "UP",
  9. responsibleInstanceCount: 0
  10. }

Query server list

Description

Query server list

Request Type

GET

Request Path

  1. /nacos/v1/ns/operator/servers

Request Parameters

NameTypeRequiredDescription
healthybooleannoif return healthy servers only

Request Example

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/servers'

Response Example

  1. {
  2. servers: [
  3. {
  4. ip: "1.1.1.1",
  5. servePort: 8848,
  6. site: "unknown",
  7. weight: 1,
  8. adWeight: 0,
  9. alive: false,
  10. lastRefTime: 0,
  11. lastRefTimeStr: null,
  12. key: "1.1.1.1:8848"
  13. },
  14. {
  15. ip: "1.1.1.2",
  16. servePort: 8848,
  17. site: "unknown",
  18. weight: 1,
  19. adWeight: 0,
  20. alive: false,
  21. lastRefTime: 0,
  22. lastRefTimeStr: null,
  23. key: "1.1.1.2:8848"
  24. },
  25. {
  26. ip: "1.1.1.3",
  27. servePort: 8848,
  28. site: "unknown",
  29. weight: 1,
  30. adWeight: 0,
  31. alive: false,
  32. lastRefTime: 0,
  33. lastRefTimeStr: null,
  34. key: "1.1.1.3:8848"
  35. }
  36. ]
  37. }

Query the leader of current cluster

Description

Query the leader of current cluster

Request Type

GET

Request Path

  1. /nacos/v1/ns/raft/leader

Request Parameters

Request Example

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/raft/leader'

Response Example

  1. {
  2. leader: "{"heartbeatDueMs":2500,"ip":"1.1.1.1:8848","leaderDueMs":12853,"state":"LEADER","term":54202,"voteFor":"1.1.1.1:8848"}"
  3. }

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

  1. /nacos/v1/ns/health/instance

Request Parameters

NameTypeRequiredDescription
serviceNameStringyesservice name
groupNameStringnogroup name
namespaceIdStringnonamespace id
clusterNameStringnocluster name
ipStringyesip of instance
portintyesport of instance
healthybooleanyesif healthy

Request Example

  1. 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