IBM Service Discovery API

Beta

IBM Service Discovery API

+ Day(s) remaining in the trial

Overview

Service Discovery is a core service within a cloud microservices architecture you can use to accelerate the development of your applications in the cloud environment. . Use IBM Service Discovery so your cloud applications can rapidly locate and use one or more instances of a microservice, reducing manual management of your solution. Service Discovery provides the framework to register instances in the Service Discovery registry. Service Discovery is not aware of the underlying implementation or architecture of microservice instances that are registered. Instances that are running on Cloud Foundry, IBM Containers, or IBM Virtual Servers, or any mix of these implementations, can be registered with Service Discovery. When mixing microservices running on different architecture implementations, there may be network visibility considerations to be aware of. . The REST APIs described here include: . - Registration of microservice instances with Service Discovery - Management of microservice instance registrations in Service Discovery - Discovering microservice instances registered with Service Discovery . The [Service Discovery documentation in Bluemix](https://console.ng.bluemix.net/docs/services/ServiceDiscovery/index.html) provides an overview and summary of what Service Discovery is and how it works. The documentation also discusses the mixing of architecture implementations and the corresponding network considerations. Review that information to gain a foundation for using the Service Discovery REST APIs documented here.

Security

Keys

Pick a key to use with this API. Make sure you are logged in with your IBM id for your keys to be populated in the dropdown below. By selecting a key, it will be pre-filled for each endpoint in the Documentation section that can be used with the built-in testing. If you want to change which key to use for a particular endpoint, you can do so at the endpoint in the Documentation section.
You can manage your API keys in the <MyAPIs> section. API keys authenticate you to your subscription, so make sure to keep them secret. Do not share the X-IBM-Client-Secret portion of any API key in publicly accessible places such as GitHub, or client-side code.



Manage your keys
 

Documentation

IBM Service Discovery API:

Instances

Instances
Delete an instance registration
Removes the registration of a microservice instance from the Service Discovery registry.

DELETE   /api/v1/instances/{id}

			https://servicediscovery.ng.bluemix.net/api/v1/instances/{id}
		
Keys
Header parameters

Authorization: Bearer

HEADER , required

was assigned when Service Discovery was provisioned. See [Service Discovery service credentials](https://console.ng.bluemix.net/docs/services/ServiceDiscovery/svc_discovery_registering.html#svc_discovery_get_credentials).

Content-Length: 0

HEADER , required

Indicates a zero length body

Path and Query parameters

id

URL , required

Unique ID of the instance in the Service Discovery registry. When the instance was registered, the URL for this DELETE was returned in the response in the 'links : self' value. The {id} is also in the response when listing registered instances.

Request code
Response model

200

OK

Body

400

Bad request.

Body

error

STRING , optional

401

Authorization failure, invalid token

Body

error

STRING , optional

410

Failed to deregister instance

Body

error

STRING , optional

Response example

200

OK

								
							

400

Bad request.

								{
  "error" : string
}
							

401

Authorization failure, invalid token

								{
  "error" : string
}
							

410

Failed to deregister instance

								{
  "error" : string
}
							
List registered instances
Returns a list of the microservice instances registered with Service Discovery. Optional query parameters can be input to return a specific list of instances that correspond to the input parameter data. If query parameters are not specified, all registered instances with a status of 'UP' will be returned.

GET   /api/v1/instances

			https://servicediscovery.ng.bluemix.net/api/v1/instances
		
Keys
Header parameters

Authorization: Bearer

HEADER , required

was assigned when Service Discovery was provisioned. See [Service Discovery service credentials](https://console.ng.bluemix.net/docs/services/ServiceDiscovery/svc_discovery_registering.html#svc_discovery_get_credentials).

Path and Query parameters

fields

STRING , optional

Comma separated list of fields to include in the response. If this parameter is not specified, all fields are returned. For example: api/v1/instances?fields=status,endpoint,service_name

service_name

STRING , optional

The name of the microservice associated with the registered instances.

status

STRING , optional

The status of the instances. 'ALL' returns all instances for all statuses. 'UP' is the default value when this parameter is not specified.

tags

STRING , optional

Comma separated list of tags that were specified when microservice instances were registered. For exanmple: api/v1/instances?tags=tagA,tagB

Request code
Response model

200

An Instances object with a list of registered instances.

Body

instances

object , optional

id

STRING , optional

The unique ID of the instance in the Service Discovery registry.

service_name

STRING , optional

The name of the microservice under which the instance is registered in the Service Discovery registry.

endpoint

object , optional

ttl

INTEGER , optional

The number of seconds that the registered instance is considered healthy and available.

status

STRING , optional

A microservice instance that is active and available: UP. An instance that is starting or initializing: STARTING. An instance that is not currently available or servicing heartbeats but remains registered: OUT_OF_SERVICE.

metadata

object , optional

last_heartbeat

DATE , optional

Time stamp when last heartbeat was processed.

tags

ARRAY , optional

User defined tags to further identify or describe the registered instance.

type

STRING , optional

Protocol used to call the instance. Valid values: tcp, http, udp, user

value

STRING , optional

Network address for endpoint type. Valid values are IP address, URL, udp value, user defined

name

STRING , optional

The unique name for this instance of the microservice in the Service Discovery registry.

400

Bad request.

Body

error

STRING , optional

undefined

401

Authorization failure, invalid token

Body

error

STRING , optional

undefined

Response example

200

An Instances object with a list of registered instances.

								{
  "instances" : {
    "id" : string,
    "service_name" : string,
    "endpoint" : {
    "type" : string,
    "value" : string
  },
    "ttl" : integer,
    "status" : string,
    "metadata" : {
    "name" : string
  },
    "last_heartbeat" : date,
    "tags" : [array]
  }
}
							

400

Bad request.

								{
  "error" : string
}
							

401

Authorization failure, invalid token

								{
  "error" : string
}
							
Register an instance
Registers a microservice instance in Service Discovery. When an instance is registered in Service Discovery, information is stored that an application would use to identify and call the instance. The information includes the name of the associated microservice, the name of this specific instance, current status, the endpoint communication protocol, and an endpoint network address. Additionally, metadata and user defined tags can be specified that an application can use to further identify a specific instance. To change or update the information for a registered instance, this API would be used specifying updated information.

POST   /api/v1/instances

			https://servicediscovery.ng.bluemix.net/api/v1/instances
		
Keys
Header parameters

Authorization: Bearer

HEADER , required

was assigned when Service Discovery was provisioned. See [Service Discovery service credentials](https://console.ng.bluemix.net/docs/services/ServiceDiscovery/svc_discovery_registering.html#svc_discovery_get_credentials).

Request code
Request model

service_name

STRING , optional

The name of the microservice this instance registration is associated with.

endpoint

object , optional

type

STRING , optional

Protocol to call the instance. Valid values: tcp, http, udp, user

value

STRING , optional

Network address for input type. Valid values are IP address, URL, udp value, user defined

status

STRING , optional

A microservice instance that is active and available has a value of UP. An instance that is starting or initializing has a status value of STARTING. An instance that is not currently available or is servicing heartbeats but remains registered, has a status of OUT_OF_SERVICE. You can update the status by reregistering the instance with a different status value.

ttl

INTEGER , optional

The number of seconds to wait before the microservice instance registration is expired. The registration is renewed using the heartbeat API. This registration renewal must occur within the seconds specified in the ttl value. This renewal/heartbeat flow provides assurance that registered microservice instances are healthy and available. Valid value range: 10 - 600

metadata

object , optional

name

STRING , optional

The unique name for the instance being registered. You can then register multiple instances of the same microservice under the same service_name

tags

ARRAY , optional

User defined tags to further identify or describe the instance being registered.

Request example
{
  "service_name": "SampleService",
  "endpoint": {
    "type": "tcp",
    "value": "100.0.0.1"
  },
  "status": "UP",
  "ttl": 30,
  "metadata": {
    "name": "sample_service_instance_1"
  },
  "tags": []
}
Response model

201

Created: The instance registration was created or renewed.

Body

id

STRING , optional

The unique identifier assigned to the microservice instance in the Service Discovery registry.

ttl

INTEGER , optional

The number of seconds the microservice instance remains registered in Service Discovery. If the input value was less than 10 or greater than 600, this returned value is what the ttl was set to.

links

object , optional

self

STRING , optional

The URL to input on the DELETE API to remove a registered instance from the Service Discovery registry.

heartbeat

STRING , optional

The URL to use to renew the registration for the instance which sends a heartbeat to Service Discovery. This indicates that the registered instance is healthy and active.

400

Bad request.

Body

error

STRING , optional

undefined

401

Authorization failure, invalid token

Body

error

STRING , optional

undefined

Response example

201

Created: The instance registration was created or renewed.

								{
  "id" : string,
  "ttl" : integer,
  "links" : {
    "self" : string,
    "heartbeat" : string
  }
}
							

400

Bad request.

								{
  "error" : string
}
							

401

Authorization failure, invalid token

								{
  "error" : string
}
							
Renew the registration of an instance
Renews the registration of the microservice instance. The instance is identified in the API path parameter by the unique ID that was assigned to the instance when it was registered with Service Discovery. Calling this API sends a heartbeat to Service Discovery to indicate the instance is healthy and available. If the registration is not renewed using this heartbeat call, Service Discovery will remove the instance from the registry and the instance will need to be registered again.

PUT   /api/v1/instances/{id}/heartbeat

			https://servicediscovery.ng.bluemix.net/api/v1/instances/{id}/heartbeat
		
Keys
Header parameters

Authorization: Bearer

HEADER , required

was assigned when Service Discovery was provisioned. See [Service Discovery service credentials](https://console.ng.bluemix.net/docs/services/ServiceDiscovery/svc_discovery_registering.html#svc_discovery_get_credentials).

Path and Query parameters

id

URL , required

The unique ID of the instance in the Service Discovery registry. When the instance was registered, this URL was returned in the response as the 'links : heartbeat' value. The {id} is also in the response when listing registered instances.

Request code
Response model

200

OK

Body

400

Bad request.

Body

error

STRING , optional

401

Authorization failure, invalid token

Body

error

STRING , optional

410

Failed to renew instance registration

Body

error

STRING , optional

Response example

200

OK

								
							

400

Bad request.

								{
  "error" : string
}
							

401

Authorization failure, invalid token

								{
  "error" : string
}
							

410

Failed to renew instance registration

								{
  "error" : string
}
							

Loading content...