Skip to content

Open API Guide

Nacos 2.X is compatible with Nacos 1.X OpenAPI, please refer to the document Nacos1.X OpenAPI.

Attension: OpenAPIs which do not specify a supported version, will be supported since 2.2.0.

Documentation Conventions

API unified return body format

In Nacos 2.X, the response to all interface requests is a return body of type json, which has the same format

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

The meanings of the fields in the return body are shown in the following table

nametypedescription
code intError code,0 means the execution succeeded, non-0 means the execution failed in one of the cases
messageStringError code prompt message, execution success as “success
dataAnyReturn data, detailed error message in case of execution failure

Since the code field is the same as the message field in case of successful execution, only the data field of the returned data will be introduced in the subsequent introduction of the returned results of the interface

API error code summary

The error codes and corresponding prompt messages in the return body of the API interface are summarized in the following table

Error Codemessagemeaning
0successSuccessful execution
10000parameter missingMissing parameters
10001access deniedAccess Denied
10002data access errorData access error
20001'tenant' parameter errortenant parameter error
20002parameter validate errorParameter validation error
20003MediaType ErrorMediaType error for HTTP requests
20004resource not foundResource not found
20005resource conflictResource access conflicts
20006config listener is nullListening configuration is empty
20007config listener errorListening configuration error
20008invalid dataIdInvalid dataId (authentication failure)
20009parameter mismatchRequest parameter mismatch
21000service name errorserviceName error
21001weight errorweight error
21002instance metadata errorInstance metadata error
21003instance not foundinstance not found
21004instance errorinstance error
21005service metadata errorService metadata error
21006selector errorselector error
21007service already existService already exists
21008service not existService does not exist
21009service delete failureService instance exists, service deletion failed
21010healthy param misshealthy parameter miss
21011health check still runningHealth check is still running
22000illegal namespacenamespace is illegal
22001namespace not existNamespace does not exist
22002namespace already existNamespace already exists
23000illegal statestate is illegal
23001node info errorNode information error
23002node down failureNode offline operation error
30000server errorOther internal errors

Configuration Management

Get configuration

Description

Get the specified configuration

Request Method

GET

Request URL

/nacos/v2/cs/config

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespace, default is public
groupStringYConfig group name
dataIdStringYConfig name
tagStringNTag

Return Data

ParameterTypeDescription
dataStringConfig content

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public'
  • Response Example

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

Publish configuration

Description

Publish the specified configuration

Update the configuration when it already exists

Request Method

POST

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/cs/config

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespace, default is public
groupStringYConfig group
dataIdStringYConfig name
contentStringYConfig content
tagStringNTag
appNameStringNApplication name
srcUserStringNSource user
configTagsStringNConfigure Tag list, can be multiple, comma separated
descStringNConfig description
useStringN-
effectStringN-
typeStringNConfig type
schemaStringN-

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'dataId=nacos.example' \
    -d 'group=DEFAULT_GROUP' \
    -d 'namespaceId=public' \
    -d 'content=contentTest' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/cs/config'
  • Response Example

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

Delete configuration

Description

Delete the specified configuration

Request Method

DELETE

Request URL

/nacos/v2/cs/config

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespace, default is public
groupStringYConfig group name
dataIdStringYConfig name
tagStringNTag

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public'
  • Response Example

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

Query list of history configuration

Description

Get a list of historical versions of the specified configuration

Request Method

GET

Request URL

/nacos/v2/cs/history/list

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespace, default is public
groupStringYConfig group name
dataIdStringYConfig name
pageNointNCurrent page, default is 1
pageSizeintNNumber of page entries, default is 100, maximum is 500

Return Data

ParameterTypeDescription
dataObjectPaging Search Results
data.totalCountintTotal
data.pageNumberintCurrent page
data.pagesAvailableintTotal number of pages
data.pageItemsObject[]List of historical configuration items, refer to Historical configuration item

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/list?dataId=nacos.example&group=com.alibaba.nacos&namespaceId='
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
    {
    "id": "203",
    "lastId": -1,
    "dataId": "nacos.example",
    "group": "com.alibaba.nacos",
    "tenant": "",
    "appName": "",
    "md5": "9f67e6977b100e00cab385a75597db58",
    "content": "contentTest",
    "srcIp": "0:0:0:0:0:0:0:1",
    "srcUser": null,
    "opType": "I",
    "createdTime": "2010-05-04T16:00:00.000+0000",
    "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
    }
    ]
    }
    }

Query the history details of the configuration

Description

Get the historical configuration of the specified version

Request Method

GET

Request URL

/nacos/v2/cs/history

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespace, default is public
groupStringYConfig group name
dataIdStringYConfig name
nidlongYHistory configuration id

Return Data

ParameterTypeDescription
dataObjectHistorical configuration item
data.idStringConfig id
data.lastIdint
data.dataIdStringConfig name
data.groupStringconfig group
data.tenantStringTenant (namespace)
data.appNameStringApplication name
data.md5StringThe md5 value of config content
data.contentStringConfig content
data.srcIpStringSource ip
data.srcUserStringSource user
data.opTypeStringOperator type
data.createdTimeStringCreation time
data.lastModifiedTimeStringLast modified time
data.encryptedDataKeyString

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=&nid=203'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "id": "203",
    "lastId": -1,
    "dataId": "nacos.example",
    "group": "com.alibaba.nacos",
    "tenant": "",
    "appName": "",
    "md5": "9f67e6977b100e00cab385a75597db58",
    "content": "contentTest",
    "srcIp": "0:0:0:0:0:0:0:1",
    "srcUser": null,
    "opType": "I",
    "createdTime": "2010-05-04T16:00:00.000+0000",
    "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
    }
    }

Query the previous version of the configuration

Description

Get the previous version of the specified configuration

Request Method

GET

Request URL

/nacos/v2/cs/history/previous

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespace, default is public
groupStringYConfig group name
dataIdStringYConfig name
idlongYconfig id

Return Data

ParameterTypeDescription
dataObjectHistorical configuration item, refer to Historical configuration item

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/previous?id=309135486247505920&dataId=nacos.example&group=com.alibaba.nacos&namespaceId='
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "id": "203",
    "lastId": -1,
    "dataId": "nacos.example",
    "group": "com.alibaba.nacos",
    "tenant": "",
    "appName": "",
    "md5": "9f67e6977b100e00cab385a75597db58",
    "content": "contentTest",
    "srcIp": "0:0:0:0:0:0:0:1",
    "srcUser": null,
    "opType": "I",
    "createdTime": "2010-05-04T16:00:00.000+0000",
    "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
    }
    }

Query the list of configurations under the specified namespace

Description

Get the list of configurations under the specified namespace

Request Method

GET

Request URL

/nacos/v2/cs/history/configs

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringYNamespace

Return Data

ParameterTypeDescription
dataObject[]Config list
data.idStringconfig id
data.dataIdStringConfig name
data.groupStringConfig group
data.contentStringConfig content
data.md5Stringthe md5 value of config content
data.encryptedDataKeyString
data.tenantStringTenant (namespace)
data.appNameStringApplication name
data.typeStringconfig file Type
data.lastModifiedlongLast modified time

Only the dataId, group, tenant, appName, type fields are valid for the configuration information in the returned data, the other fields are default values

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/configs?namespaceId='
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "id": "0",
    "dataId": "nacos.example",
    "group": "com.alibaba.nacos",
    "content": null,
    "md5": null,
    "encryptedDataKey": null,
    "tenant": "",
    "appName": "",
    "type": "yaml",
    "lastModified": 0
    }
    ]
    }

Service Discovery

Register instance

Description

Register an instance

Request Method

POST

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/instance

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
ipStringYIP address
portintYPort number
clusterNameStringNCluster name, default is DEFAULT
healthybooleanNWhether to find only healthy instances, default is true
weightdoubleNInstance weights, default is 1.0
enabledbooleanNEnable or not, default is true
metadataJSON format StringNInstance metadata
ephemeralbooleanNWhether it is a temporary instance

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=test_service' \
    -d 'ip=127.0.0.1' \
    -d 'port=8090' \
    -d 'weight=0.9' \
    -d 'ephemeral=true' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/ns/instance'
  • Response Example

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

Deregister instance

Description

Deregister a specified instance

Request Method

DELETE

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/instance

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
ipStringYIP address
portintYPort number
clusterNameStringNCluster name, default is DEFAULT
healthybooleanNWhether to find only healthy instances, default is true
weightdoubleNInstance weights, default is 1.0
enabledbooleanNEnable or not, default is true
metadataJSON format StringNInstance metadata
ephemeralbooleanNWhether it is a temporary instance

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=test_service' \
    -d 'ip=127.0.0.1' \
    -d 'port=8090' \
    -d 'weight=0.9' \
    -d 'ephemeral=true' \
    -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance'
  • Response Example

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

Modify instance

Description

Modify instance information

The metadata updated through this interface has a higher priority and has the ability to remember. After the instance removed, it will still exist for a period of time. If the instance is re-registered during this period, the metadata will still be Effective. You can modify the memory time through nacos.naming.clean.expired-metadata.expired-time and nacos.naming.clean.expired-metadata.interval

Request Method

PUT

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/instance

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
ipStringYIP address
portintYPort number
clusterNameStringNCluster name, default is DEFAULT
healthybooleanNWhether to find only healthy instances, default is true
weightdoubleNInstance weights, default is 1.0
enabledbooleanNEnable or not, default is true
metadataJSON format StringNInstance metadata
ephemeralbooleanNWhether it is a temporary instance

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=test_service' \
    -d 'ip=127.0.0.1' \
    -d 'port=8090' \
    -d 'weight=0.9' \
    -d 'ephemeral=true' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance'
  • Response Example

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

Query instance detail

Description

Query the details of a specific instance

Request Method

GET

Request URL

/nacos/v2/ns/instance

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
clusterNameStringNCluster name, default is DEFAULT
ipStringYIP address
portintYPort number

Return Data

ParameterTypeDescription
dataObjectInstance details information
data.serviceNameStringService name
data.ipStringIP address
data.portintPort number
data.clusterNameStringCluster name
data.weightdoubleInstance weight
data.healthybooleanhealthy
data.instanceIdStringInstance id
data.metadatamapInstance metadata

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance?namespaceId=public&groupName=&serviceName=test_service&ip=127.0.0.1&port=8080'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "serviceName": "DEFAULT_GROUP@@test_service",
    "ip": "127.0.0.1",
    "port": 8080,
    "clusterName": "DEFAULT",
    "weight": 1.0,
    "healthy": true,
    "instanceId": null,
    "metadata": {
    "value": "1"
    }
    }
    }

Query instances

Description

Query the list of instances under the specified service

Request Method

GET

Request URL

/nacos/v2/ns/instance/list

Request Header

ParameterTypeRequiredDescription
User-AgentStringNUser agent, default is empty
Client-VersionStringNClient version, default is empty

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is empty
serviceNameStringYService name
clusterNameStringNCluster name, default is DEFAULT
ipStringNIP address, the default is empty, which means no restrictions on IP address
portintNPort numberThe default is 0, which means no restriction on port number
healthyOnlybooleanNWhether to get only healthy instances, default is false
appStringNApplication name, default is empty

Return Data

ParameterTypeDescription
dataList of instances of the specified service
data.nameStringGroup name@@Service name
data.groupNameStringGroup name
data.clustersStringCluster name
data.cacheMillisintCache name
data.hostsObject[]Instance list
data.hosts.ipStringInstance IP
data.hosts.portintInstance Port number
data.hosts.weightdoubleInstance weight
data.hosts.healthybooleanInstance healthy
data.hosts.enabledbooleanInstance is enabled
data.hosts.ephemeralbooleanWhether it is a temporary instance
data.hosts.clusterNameStringName of the cluster where the instance is located
data.hosts.serviceNameStringService name
data.hosts.metadatamapInstance metadata
data.hosts.instanceHeartBeatTimeOutintInstance heartbeat timeout time
data.hosts.ipDeleteTimeoutintInstance delete timeout time
data.hosts.instanceHeartBeatIntervalintInstance heartbeat interval
data.lastRefTimeintlast refresh time
data.checksumintchecksum
data.allIPsboolean
data.reachProtectionThresholdbooleanWhether the protection threshold is reached
data.validbooleanValid

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance/list?serviceName=test_service&ip=127.0.0.1'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "name": "DEFAULT_GROUP@@test_service",
    "groupName": "DEFAULT_GROUP",
    "clusters": "",
    "cacheMillis": 10000,
    "hosts": [
    {
    "ip": "127.0.0.1",
    "port": 8080,
    "weight": 1.0,
    "healthy": true,
    "enabled": true,
    "ephemeral": true,
    "clusterName": "DEFAULT",
    "serviceName": "DEFAULT_GROUP@@test_service",
    "metadata": {
    "value": "1"
    },
    "instanceHeartBeatTimeOut": 15000,
    "ipDeleteTimeout": 30000,
    "instanceHeartBeatInterval": 5000
    }
    ],
    "lastRefTime": 1662554390814,
    "checksum": "",
    "allIPs": false,
    "reachProtectionThreshold": false,
    "valid": true
    }
    }

Batch update instance metadata

Description

Batch update instance metadata

If the key corresponding to the metadata does not exist, add the corresponding metadata.

Request Method

PUT

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/instance/metadata/batch

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
consistencyTypeStringNPersistence type, default is empty
instancesJSON format StringNInstance list, default is empty
metadataJSON format StringYInstance metadata

Parameter Description

  • consistencyType: Persistence type of Instance, when “persist`” means update the metadata of persistent Instance; otherwise means update the metadata of temporary Instance
  • instances: Instance list to be updated, json array, locate an instance by ip+port+ephemeral+cluster, null means update the metadata of all instances under the specified service

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=test_service' \
    -d 'consistencyType=ephemeral' \
    -d 'instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]' \
    -d 'metadata={"age":"20","name":"cocolan"}' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch'
  • Response Example

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

Batch delete instance metadata

Description

Batch delete instance metadata

If the key corresponding to the metadata does not exist, then no operation is performed

Request Method

DELETE

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/instance/metadata/batch

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
consistencyTypeStringNPersistence type, default is empty
instancesJSON format StringNInstance list, default is empty
metadataJSON format StringYInstance metadata

Parameter Description

  • consistencyType: Persistence type of Instance, when “persist`” means update the metadata of persistent Instance; otherwise means update the metadata of temporary Instance
  • instances: Instance list to be updated, json array, locate an instance by ip+port+ephemeral+cluster, null means update the metadata of all instances under the specified service

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=test_service' \
    -d 'consistencyType=ephemeral' \
    -d 'instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]' \
    -d 'metadata={"age":"20","name":"cocolan"}' \
    -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch'
  • Response Example

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

Create service

Description

Create a service

Failed to create when service already exists

Request Method

POST

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/service

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
metadataJSON format StringNService metadata, default is empty
ephemeralbooleanNWhether it is a temporary instance, default is false
protectThresholdfloatNProtection threshold, default is 0
selectorJSON format StringNSelector, default is empty

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=nacos.test.1' \
    -d 'ephemeral=true' \
    -d 'metadata={"k1":"v1"}' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/ns/service'
  • Response Example

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

Delete service

Description

Delete the specified service

An error is reported when the service does not exist, and deletion fails when an instance of the service still exists

Request Method

DELETE

Request URL

/nacos/v2/ns/service

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1'
  • Response Example

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

Update service

Description

Update the specified service

Error when service does not exist

Request Method

POST

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/service

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
metadataJSON format StringNService metadata, default is empty
protectThresholdfloatNProtection threshold, default is 0
selectorJSON format StringNSelector, default is empty

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=nacos.test.1' \
    -d 'metadata={"k1":"v2"}' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/service'
  • Response Example

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

Query service

Description

Query detailed information about a specific service

Error when service does not exist

Request Method

GET

Request URL

/nacos/v2/ns/service

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is empty
serviceNameStringYService name

Return Data

ParameterTypeDescription
dataService information
data.namespaceStringNamespace
data.groupNameStringGroup name
data.serviceNameStringService name
data.clusterMapmapCluster information
data.metadatamapService metadata
data.protectThresholdfloatProtection threshold
data.selectorObjectSelector
data.ephemeralBooleanWhether it is a temporary instance

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "namespace": "public",
    "serviceName": "nacos.test.1",
    "groupName": "DEFAULT_GROUP",
    "clusterMap": {},
    "metadata": {},
    "protectThreshold": 0,
    "selector": {
    "type": "none",
    "contextType": "NONE"
    },
    "ephemeral": false
    }
    }

Query service list

Description

Check the list of eligible services

Request Method

GET

Request URL

/nacos/v2/ns/service/list

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is empty
selectorJSON format StringYSelector
pageNointNCurrent page, default is 1
pageSizeintNNumber of page, default is 20, Up to 500

Return Data

ParameterTypeDescription
dataService list
data.countStringNumber of services
data.servicesString[]Service list after paging

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service/list'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "count": 2,
    "services": [
    "nacos.test.1",
    "nacos.test.2"
    ]
    }
    }

Query system switches

Description

Query system switches

Request Method

GET

Request URL

/nacos/v2/ns/operator/switches

Return Data

ParameterTypeDescription
dataObjectSystem switch information

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "masters": null,
    "adWeightMap": {},
    "defaultPushCacheMillis": 10000,
    "clientBeatInterval": 5000,
    "defaultCacheMillis": 3000,
    "distroThreshold": 0.7,
    "healthCheckEnabled": true,
    "autoChangeHealthCheckEnabled": 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": 2000,
    "serviceStatusSynchronizationPeriodMillis": 5000,
    "disableAddIP": false,
    "sendBeatOnly": false,
    "lightBeatEnabled": true,
    "doubleWriteEnabled": false,
    "limitedUrlMap": {},
    "distroServerExpiredMillis": 10000,
    "pushGoVersion": "0.1.0",
    "pushJavaVersion": "0.1.0",
    "pushPythonVersion": "0.4.3",
    "pushCVersion": "1.0.12",
    "pushCSharpVersion": "0.9.0",
    "enableAuthentication": false,
    "overriddenServerStatus": null,
    "defaultInstanceEphemeral": true,
    "healthCheckWhiteList": [],
    "name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
    "checksum": null
    }
    }

Update system switch

Description

Update system switch

Request Method

PUT

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/operator/switches

Request Body

ParameterTypeRequiredDescription
entryStringYEntry
valueStringYValue
debugbooleanNWhether it takes effect on local machine only,true means it takes effect on local machine,false means it takes effect on cluster

Return Data

ParameterTypeDescription
dataString”ok” indicates successful execution

Example

  • Request Example

    Terminal window
    curl -d 'entry=pushEnabled' \
    -d 'value=false' \
    -d 'debug=true' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches'
  • Response Example

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

Query system metrics

Description

Query system metrics

Request Method

GET

Request URL

/nacos/v2/ns/operator/metrics

Request Parameters

ParameterTypeRequiredDescription
onlyStatusbooleanNShow status only, default is true

When onlyStatus is set to true, only the string indicating the system status is returned

Return Data

ParameterTypeDescription
dataObjectSystem metrics
data.statusStringSystem status
data.serviceCountintNumber of services
data.instanceCountintNumber of instances
data.subscribeCountintNumber of subscriptions
data.raftNotifyTaskCountintNumber of Raft notify task
data.responsibleServiceCountint
data.responsibleInstanceCountint
data.clientCountintNumber of client
data.connectionBasedClientCountintNumber of connectionBasedClient
data.ephemeralIpPortClientCountintNumber of ephemeralIpPortClient
data.persistentIpPortClientCountintNumber of persistentIpPortClient
data.responsibleClientCountint
data.cpufloatcpu utilization
data.loadfloatload
data.memfloatMemory usage

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/metrics'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "status": "UP",
    "serviceCount": 2,
    "instanceCount": 2,
    "subscribeCount": 2,
    "raftNotifyTaskCount": 0,
    "responsibleServiceCount": 0,
    "responsibleInstanceCount": 0,
    "clientCount": 2,
    "connectionBasedClientCount": 2,
    "ephemeralIpPortClientCount": 0,
    "persistentIpPortClientCount": 0,
    "responsibleClientCount": 2,
    "cpu": 0,
    "load": -1,
    "mem": 1
    }
    }

Update instance health status

Description

Update the health status of the instance

Request Method

PUT

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/ns/health/instance

Request Body

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
clusterNameStringNCluster name, default is DEFAULT
ipStringYIP address
portintYPort number
healthybooleanYhealthy

Return Data

ParameterTypeDescription
dataStringok” indicates successful execution

Example

  • Request Example

    Terminal window
    curl -d 'serviceName=nacos.test.1' \
    -d 'ip=127.0.0.1' \
    -d 'port=8080' \
    -d 'healthy=false' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/health/instance'
  • Response Example

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

Query client list (new)

Description

Query the current list of all clients

Request Method

GET

Request URL

/nacos/v2/ns/client/list

Return Data

ParameterTypeDescription
dataString[]Client id list

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/list'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    "10.128.164.35:9956#true",
    "1664358687402_127.0.0.1_2300",
    "1664358642902_127.0.0.1_2229",
    "192.168.139.1:49825#true",
    "10.128.164.35:9954#true",
    "192.168.139.1:53556#true"
    ]
    }

For different versions of the nacos client, there are different ways to create clients.

For nacos client in 1.x version, each Instance will create two clients based on ip+port, corresponding to Instance registration and service subscription, respectively, with clientId in the format ip:port#ephemeral

For nacos client in 2.x version, each Instance establishes a RPC connection, which corresponds to an RPC connection-based client with both registration and subscription functions, with clientId in the format time_ip_port

Query client (new)

Description

Query the details of the specified client

Error when client does not exist

Request Method

GET

Request URL

/nacos/v2/ns/client

Request Parameters

ParameterTypeRequiredDescription
clientIdStringYClient id

Return Data

ParameterTypeDescription
dataObjectClient Information
data.clientIdStringClient id
data.ephemeralbooleanWhether it is a temporary instance
data.lastUpdatedTimeintLast update time
data.clientTypeStringClient type
data.clientIpStringClient IP
data.clientPortStringClient port
data.connectTypeStringConnection type
data.appNameStringApplication name
data.VersionStringClient version

Only when clientType is connection, the connectType, appName and appName fields will be displayed

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client?clientId=1664527081276_127.0.0.1_4400'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "clientId": "1664527081276_127.0.0.1_4400",
    "ephemeral": true,
    "lastUpdatedTime": 1664527081642,
    "clientType": "connection",
    "connectType": "GRPC",
    "appName": "-",
    "version": "Nacos-Java-Client:v2.1.0",
    "clientIp": "10.128.164.35",
    "clientPort": "4400"
    }
    }

Query the registration information of the client (new)

Description

Query the registration information of the specified client

Error when client does not exist

Request Method

GET

Request URL

/nacos/v2/ns/client/publish/list

Request Parameters

ParameterTypeRequiredDescription
clientIdStringYClient id

Return Data

ParameterTypeDescription
dataObject[]List of services registered by the client
data.namespaceStringNamespace
data.groupStringGroup name
data.serviceNameStringService name
data.registeredInstanceObjectInstances registered under this service
data.registeredInstance.ipStringIP address
data.registeredInstance.portintPort number
data.registeredInstance.clusterStringCluster name

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "namespace": "public",
    "group": "DEFAULT_GROUP",
    "serviceName": "nacos.test.1",
    "registeredInstance": {
    "ip": "10.128.164.35",
    "port": 9950,
    "cluster": "DEFAULT"
    }
    }
    ]
    }

Query the subscription information of the client (new)

Description

Query the subscription information of the specified client

Error when client does not exist

Request Method

GET

Request URL

/nacos/v2/ns/client/subscribe/list

Request Parameters

ParameterTypeRequiredDescription
clientIdStringYClient id

Return Data

ParameterTypeDescription
dataObject[]List of services to which the client is subscribed
data.namespaceStringNamespace
data.groupStringGroup name
data.serviceNameStringService name
data.subscriberInfoObjectSubscription Information
data.subscriberInfo.appStringApplication
data.subscriberInfo.agentStringClient Information
data.subscriberInfo.addrStringAddress

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "namespace": "public",
    "group": "DEFAULT_GROUP",
    "serviceName": "nacos.test.1",
    "subscriberInfo": {
    "app": "unknown",
    "agent": "Nacos-Java-Client:v2.1.0",
    "addr": "10.128.164.35"
    }
    }
    ]
    }

Query the client that registered the specified service (new)

Description

Query the client information of the registered specified service

Request Method

GET

Request URL

/nacos/v2/ns/client/service/publisher/list

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
ephemeralbooleanNWhether it is a temporary instance
ipStringNIP address, default is empty, indicates unrestricted IP address
portintNPort number, default is empty, Indicates unrestricted Port number

Return Data

ParameterTypeDescription
dataClient list
data.clientIdStringClient id
data.ipStringClient IP
data.portintClient port

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/publisher/list?serviceName=nacos.test.1&ip=&port='
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "clientId": "1664527081276_127.0.0.1_4400",
    "ip": "10.128.164.35",
    "port": 9950
    },
    {
    "clientId": "10.128.164.35:9954#true",
    "ip": "10.128.164.35",
    "port": 9954
    }
    ]
    }

Query the information of clients subscribed to the specified service (new)

Description

Query the clients subscribed to the specified service

Request Method

GET

Request URL

/nacos/v2/ns/client/service/subscriber/list

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringNNamespaceId, default is public
groupNameStringNGroup name, default is DEFAULT_GROUP
serviceNameStringYService name
ephemeralbooleanNWhether it is a temporary instance
ipStringNIP address, default is empty, indicates unrestricted IP address
portintNPort number, default is empty, Indicates unrestricted Port number

Return Data

ParameterTypeDescription
dataClient list
data.clientIdStringClient id
data.ipStringClient IP
data.portintClient port

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/subscriber/list?serviceName=nacos.test.1&ip=&port='
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "clientId": "1664527125645_127.0.0.1_4443",
    "ip": "10.128.164.35",
    "port": 0
    },
    {
    "clientId": "172.24.144.1:54126#true",
    "ip": "172.24.144.1",
    "port": 54126
    }
    ]
    }

Namespace

Query namespaces

Description

Query all namespaces

Request Method

GET

Request URL

/nacos/v2/console/namespace/list

Return Data

ParameterTypeDescription
dataObject[]Namespaces
data.namespaceStringNamespaceID
data.namespaceShowNameStringNamespace name
data.namespaceDescStringNamespace description
data.quotaintthe capacity of Namespace
data.configCountintNumber of configs under namespace
data.typeintNamespace type

There are 3 types of Namespace, 0 - Global Namespace 1 - Default Private Namespace 2 - Custom Namespace

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace/list'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "namespace": "",
    "namespaceShowName": "public",
    "namespaceDesc": null,
    "quota": 200,
    "configCount": 1,
    "type": 0
    }
    ]
    }

Query namespace

Description

Query information about a specific Namespace

Error when namespace does not exist

Request Method

GET

Request URL

/nacos/v2/console/namespace

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringYNamespaceId

Return Data

ParameterTypeDescription
dataObjectNamespace
data.namespaceStringNamespace ID
data.namespaceShowNameStringNamespace name
data.namespaceDescStringNamespace description
data.quotaintthe capacity of Namespace
data.configCountintNumber of configs under namespace
data.typeintNamespace type

There are 3 types of Namespace, 0 - Global Namespace 1 - Default Private Namespace 2 - Custom Namespace

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=test_namespace'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "namespace": "test_namespace",
    "namespaceShowName": "test",
    "namespaceDesc": null,
    "quota": 200,
    "configCount": 0,
    "type": 2
    }
    }

Create namespace

Description

Create a namespace

Error when namespace already exists

Request Method

POST

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/console/namespace

Request Body

ParameterTypeRequiredDescription
namespaceIdStringYNamespaceId
namespaceNameStringYNamespace name
namespaceDescStringNNamespace Description

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'namespaceId=test_namespace' \
    -d 'namespaceName=test' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/console/namespace'
  • Response Example

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

Update namespace

Description

Edit namespace

Request Method

PUT

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/console/namespace

Request Body

ParameterTypeRequiredDescription
namespaceIdStringYNamespaceId
namespaceNameStringYNamespace name
namespaceDescStringNNamespace Description

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'namespaceId=test_namespace' \
    -d 'namespaceName=test.nacos' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/console/namespace'
  • Response Example

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

Delete namespace

Description

Delete the specified namespace

Request Method

DELETE

Request URL

/nacos/v2/console/namespace

Request Parameters

ParameterTypeRequiredDescription
namespaceIdStringYNamespaceId

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'namespaceId=test_namespace' \
    -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace'
  • Response Example

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

Cluster

Query the current node

Description

Query the current nacos node

Request Method

GET

Request URL

/nacos/v2/core/cluster/node/self

Return Data

ParameterTypeDescription
dataObjectCurrent node
data.ipStringNode IP address
data.portintNode port
data.stateStringNode status
data.extendInfoObjectNode extend information
data.addressStringNode address (IP:port
data.failAccessCntintNumber of failed access
data.abilitiesObject

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": {
    "ip": "10.128.164.35",
    "port": 8848,
    "state": "UP",
    "extendInfo": {
    "lastRefreshTime": 1664521263623,
    "raftMetaData": {
    "metaDataMap": {
    "naming_instance_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_persistent_service_v2": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_service_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    }
    }
    },
    "raftPort": "7848",
    "readyToUpgrade": true,
    "version": "2.1.0"
    },
    "address": "10.128.164.35:8848",
    "failAccessCnt": 0,
    "abilities": {
    "remoteAbility": {
    "supportRemoteConnection": true
    },
    "configAbility": {
    "supportRemoteMetrics": false
    },
    "namingAbility": {
    "supportJraft": true
    }
    }
    }
    }

Query the list of cluster nodes

Description

Query the information of all nodes in the cluster

Request Method

GET

Request URL

/nacos/v2/core/cluster/node/list

Request Parameters

ParameterTypeRequiredDescription
addressStringNNode address, default is empty
stateStringNNode status, default is empty

addresscorresponds to the prefix match condition of the Node address to be queried, and is not restricted when it is empty

statecorresponds to the filter condition of node status and is not restricted when it is empty

Return Data

ParameterTypeDescription
dataObject[]Node list, refer to Node info

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list'
  • Response Example

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "ip": "10.128.164.35",
    "port": 8848,
    "state": "UP",
    "extendInfo": {
    "lastRefreshTime": 1664521263623,
    "raftMetaData": {
    "metaDataMap": {
    "naming_instance_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_persistent_service_v2": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_service_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    }
    }
    },
    "raftPort": "7848",
    "readyToUpgrade": true,
    "version": "2.1.0"
    },
    "address": "10.128.164.35:8848",
    "failAccessCnt": 0,
    "abilities": {
    "remoteAbility": {
    "supportRemoteConnection": true
    },
    "configAbility": {
    "supportRemoteMetrics": false
    },
    "namingAbility": {
    "supportJraft": true
    }
    }
    }
    ]
    }

Query the current node health status

Description

Query the current nacos node health status

Request Method

GET

Request URL

/nacos/v2/core/cluster/node/self/health

Return Data

ParameterTypeDescription
dataStringCurrent node health status

Node has five states: STARTING, UP, SUSPICIOUS, DOWN and ISOLATION.

Example

  • Request Example

    Terminal window
    curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self/health'
  • Response Example

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

Switch addressing modes

Description

Switch addressing modes

Request Method

PUT

Content-Type:application/x-www-form-urlencoded

Request URL

/nacos/v2/core/cluster/lookup

Request Body

ParameterTypeRequiredDescription
typeStringYAddressing mode

There are two addressing modes: file (file configuration) and address-server (address server)

Return Data

ParameterTypeDescription
databooleanWhether the execution is successful

Example

  • Request Example

    Terminal window
    curl -d 'type=file' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/core/cluster/lookup'
  • Response Example

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