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
  • API error code summary

• Configuration Management

  • Get configuration
  • Publish configuration
  • Delete configuration
  • Query list of history configuration
  • Query the history details of the configuration
  • Query the previous version of the configuration
  • Query the list of configurations under the specified namespace

• Service Discovery

  • Register instance
  • Deregister instance
  • Modify instance
  • Query instance detail
  • Query instances
  • Batch update instance metadata(Beta)
  • Batch delete instance metadata(Beta)
  • Create service
  • Delete service
  • Update service
  • Query service
  • Query service list
  • Query system switches
  • Update system switch
  • Query system metrics
  • Update instance health status
  • Query client list (new)
  • Query client (new)
  • Query the registration information of the client (new)
  • Query the subscription information of the client (new)
  • Query the client that registered the specified service (new)
  • Query the information of clients subscribed to the specified service (new)

• Namespace

  • Query namespaces
  • Query namespace
  • Create namespace
  • Update namespace
  • Delete namespace

• Cluster

  • Query the current node
  • Query the list of cluster nodes
  • Query the current node health status
  • Switch addressing modes

• Connection Load Management

  • Query the List of Current Node Client Connections
  • Reload the Number of Current Node Client Connections
  • Intelligently Balance the Number of Client Connections in the Cluster
  • Reset a Specific Client Connection
  • Get SDK Metrics for the Cluster

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

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

Configuration Management

Get configuration

Description

Get the specified configuration

Request Method

GET

Request URL

/nacos/v2/cs/config

Request Parameters

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

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

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Request Parameters

Return Data

Example

• Request Example

  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

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

Example

• Request Example

  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

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

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Example

• Request Example

  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

Return Data

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

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

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

Example

• Request Example

  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

Return Data

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

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Return Data

Example

• Request Example

  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

Example

• Request Example

  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

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

Example

• Request Example

  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

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

Example

• Request Example

  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

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

Return Data

Example

• Request Example

  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
  }

Connection Load Management

Query the List of Current Node Client Connections

Description

Query the list of client connections on the current Nacos node.

Request Method

GET

Request URL

/nacos/v2/core/loader/current

Return Data

Example

• Request Example

curl -X GET 'http://localhost:8848/nacos/v2/core/loader/current'

• Response Example

{
    "1697424543845_127.0.0.1_11547": {
        "traced": false,
        "abilityTable": null,
        "metaInfo": {
            "connectType": "GRPC",
            "clientIp": "192.168.49.1",
            "localPort": 9848,
            "version": "Nacos-Java-Client:v2.1.0",
            "connectionId": "1697424543845_127.0.0.1_11547",
            "createTime": "2023-10-16T10:49:03.907+08:00",
            "lastActiveTime": 1697424869827,
            "appName": "unknown",
            "tenant": "",
            "labels": {
                "source": "sdk",
                "taskId": "0",
                "module": "config",
                "AppName": "unknown"
            },
            "tag": null,
            "sdkSource": true,
            "clusterSource": false
        },
        "connected": true,
        "labels": {
            "source": "sdk",
            "taskId": "0",
            "module": "config",
            "AppName": "unknown"
        }
    }
}

Reload the Number of Current Node Client Connections

Description

Reload the number of client connections on the current Nacos node.

Request Method

GET

Request URL

/nacos/v2/core/loader/current/reloadCurrent

Request Parameters

Return Data

Example

• Request Example

  curl -X GET 'http://localhost:8848/nacos/v2/core/loader/reloadCurrent?count=1&redirectAddress=127.0.0.1:8848'

• Response Example

  success

Intelligently Balance the Number of Client Connections in the Cluster

Description

Intelligently balance the client connections among all nodes in the Nacos cluster.

Request Method

GET

Request URL

/nacos/v2/core/loader/current/smartReloadCluster

Request Parameters

Return Data

Example

• Request Example

  curl -X GET 'http://localhost:8848/nacos/v2/core/loader/smartReloadCluster?loaderFactor=1'

• Response Example

  Ok

Reset a Specific Client Connection

Description

Send a connection reset request based on the SDK connection ID.