+{"openapi":"3.1.0","info":{"title":"Nacos HTTP Client API","description":"Nacos HTTP Client API openAPI(swagger) type document，used for some program languages that no support grpc feature to develop Nacos client.","license":{"name":"Apache 2.0","url":"https://github.com/alibaba/nacos/blob/develop/LICENSE"},"version":"3.0.0-BETA"},"servers":[{"url":"http://localhost:8848/nacos","description":"Generated server url"}],"tags":[{"name":"Nacos Naming HTTP Client APIs","description":"**HTTP Client APIs for Nacos Naming, used for service instance registration, deregistration, and querying instance lists. Note:** In Nacos 3.X, the HTTP Client APIs do `NOT` provide interfaces to retrieve all service names or other system-wide operations. `Ordinary applications`, `microservices`, and `non-management/non-gateway applications` **should only require** registering themselves as an instance of a specific service, deregistering an instance, or fetching instance lists of known downstream services for direct business calls. **They should NOT need** to retrieve all services in the registry. To obtain the full service list, use the **Admin APIs**.","x-module":{"module":"naming"}},{"name":"Nacos Config HTTP Client APIs","description":"**HTTP Client APIs for Nacos Configuration Center, used for fetching configuration content. Note:** In Nacos 3.X, the HTTP Client APIs do `NOT` support configuration publishing or deletion. `Ordinary applications`, `microservices`, and `non-management/non-gateway applications` **should act as consumers** rather than publishers of configurations. For configuration publishing/deletion needs, use the **Admin APIs**.","x-module":{"module":"config"}}],"paths":{"/v3/client/ns/instance":{"post":{"tags":["Nacos Naming HTTP Client APIs"],"summary":"Register/Heartbeat an instance","description":"Registers or renews an instance in a specified service. **Note:** When using the HTTP Client API to register an ephemeral instance, periodic heartbeat renewal is required. In Nacos 3.X, the heartbeat API is merged with registration. The `heartBeat` parameter distinguishes between registration and heartbeat requests. During heartbeats, the server ignores parameters like `healthy`, `weight`, `enabled`, and `metadata`. If a heartbeat response returns error code `21003`, the instance has been expired and removed. The client should re-register with full metadata (setting `heartBeat=false`) before retrying heartbeat. While repeated registration can also renew the instance, this consumes more resources; prefer heartbeating after a successful initial registration for performance efficiency.","operationId":"register","parameters":[{"name":"namespaceId","in":"query","example":"public"},{"name":"groupName","in":"query","example":"DEFAULT_GROUP"},{"name":"serviceName","in":"query","required":true,"example":"test"},{"name":"clusterName","in":"query","example":"DEFAULT"},{"name":"ip","in":"query","required":true,"example":"127.0.0.1"},{"name":"port","in":"query","required":true,"example":8080},{"name":"weight","in":"query","example":1.0},{"name":"healthy","in":"query","example":true},{"name":"ephemeral","in":"query","example":true},{"name":"enabled","in":"query","example":true},{"name":"metadata","in":"query","example":{"zone":"a"}},{"name":"heartBeat","in":"query","example":false}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result<String>","example":{"code":0,"message":"success","data":"ok"}}}}}},"security":[{"nacos":[]}]},"delete":{"tags":["Nacos Naming HTTP Client APIs"],"summary":"Deregister an instance","description":"Deregisters an instance from a specified service.","operationId":"deregister","parameters":[{"name":"namespaceId","in":"query","example":"public"},{"name":"groupName","in":"query","example":"DEFAULT_GROUP"},{"name":"serviceName","in":"query","required":true,"example":"test"},{"name":"clusterName","in":"query","example":"DEFAULT"},{"name":"ip","in":"query","required":true,"example":"127.0.0.1"},{"name":"port","in":"query","required":true,"example":8080}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result<String>","example":{"code":0,"message":"success","data":"ok"}}}}}},"security":[{"nacos":[]}]}},"/v3/client/ns/instance/list":{"get":{"tags":["Nacos Naming HTTP Client APIs"],"summary":"List service instances","description":"Retrieves the list of instances under a specific service. **Note:** As Nacos 3.X will deprecate UDP-based event pushing, clients unable to use gRPC long-polling connections should periodically poll instance lists through HTTP requests to stay synchronized with registry changes for service subscription purposes.","operationId":"list","parameters":[{"name":"pageNo","in":"query","required":true,"example":1},{"name":"pageSize","in":"query","required":true,"example":100},{"name":"namespaceId","in":"query","example":"public"},{"name":"groupName","in":"query","example":"DEFAULT_GROUP"},{"name":"serviceName","in":"query","required":true,"example":"test"},{"name":"clusterName","in":"query","example":"DEFAULT"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result<List<Instance>>","example":{"code":0,"message":"success","data":[{"ip":"127.0.0.1","port":3306,"weight":1.0,"healthy":true,"enabled":true,"ephemeral":true,"clusterName":"DEFAULT","serviceName":"DEFAULT_GROUP@@test1","metadata":{},"ipDeleteTimeout":30000,"instanceIdGenerator":"simple","instanceHeartBeatInterval":5000,"instanceHeartBeatTimeOut":15000}]}}}}}},"security":[{"nacos":[]}]}},"/v3/client/cs/config":{"get":{"tags":["Nacos Config HTTP Client APIs"],"summary":"Get configuration content","description":"Retrieves the content of a specific configuration. **Note:** Since Nacos 3.X will remove long-polling based configuration listening, clients should instead periodically call the `Get Configuration` API and compare MD5 checksums to detect and reload updated configurations.","operationId":"getConfig","parameters":[{"name":"namespaceId","in":"query","example":"public"},{"name":"groupName","in":"query","required":true,"example":"DEFAULT_GROUP"},{"name":"dataId","in":"query","required":true,"example":"test"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result<ConfigQueryResponse>","example":{"code":0,"message":"success","data":{"resultCode":200,"errorCode":0,"message":null,"requestId":null,"content":"test","encryptedDataKey":null,"contentType":"text","md5":"098f6bcd4621d373cade4e832627b4f6","lastModified":1743151634823,"tag":null,"beta":false,"success":true}}}}}}},"security":[{"nacos":[]}]}}},"components":{"schemas":{"ConfigQueryResponse":{"properties":{"resultCode":{"type":"integer","format":"int32"},"errorCode":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"content":{"type":"string"},"encryptedDataKey":{"type":"string"},"contentType":{"type":"string"},"md5":{"type":"string"},"lastModified":{"type":"integer","format":"int64"},"tag":{"type":"string"},"beta":{"type":"boolean"},"success":{"type":"boolean"}}},"Result<String>":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"string"}}},"Result<ConfigQueryResponse>":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"object","$ref":"#/components/schemas/ConfigQueryResponse"}}},"Instance":{"properties":{"instanceId":{"type":"string"},"ip":{"type":"string"},"port":{"type":"integer","format":"int32"},"weight":{"type":"number","format":"double"},"healthy":{"type":"boolean"},"enabled":{"type":"boolean"},"ephemeral":{"type":"boolean"},"clusterName":{"type":"string"},"serviceName":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"ipDeleteTimeout":{"type":"integer","format":"int64"},"instanceIdGenerator":{"type":"string"},"instanceHeartBeatInterval":{"type":"integer","format":"int64"},"instanceHeartBeatTimeOut":{"type":"integer","format":"int64"}}},"Result<List<Instance>>":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"type":"array","items":{"properties":{"instanceId":{"type":"string"},"ip":{"type":"string"},"port":{"type":"integer","format":"int32"},"weight":{"type":"number","format":"double"},"healthy":{"type":"boolean"},"enabled":{"type":"boolean"},"ephemeral":{"type":"boolean"},"clusterName":{"type":"string"},"serviceName":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"ipDeleteTimeout":{"type":"integer","format":"int64"},"instanceIdGenerator":{"type":"string"},"instanceHeartBeatInterval":{"type":"integer","format":"int64"},"instanceHeartBeatTimeOut":{"type":"integer","format":"int64"}}}}}}},"securitySchemes":{"nacos":{"type":"apiKey","description":"Get `accessToken` by `login` API.","name":"accessToken","in":"header"}}}}
0 commit comments