Discovery Service API
This section describes how the Discovery service provided by Scriptura Engage can be used from client applications.
All requests to the Discovery Service web API must be authenticated. See OAuth 2.0 for information on how to obtain security tokens and Performing authenticated requests on how to use them.
The Web API for the Discovery Service provides several entry points to query what is conceptually one large XML document. Depending on the request URI, each request to the API addresses a certain portion of that global XML document. A sample of the global XML document is given below.
<servicediscovery href="/discovery/v2">
<nodes count="2" href="/discovery/v2/nodes">
<node node="host10" count="1" href="/discovery/v2/nodes/host10">
<service node="host10" service-class="cassandra" href="/discovery/v2/nodes/host10/cassandra">
<properties count="2" href="/discovery/v2/services/cassandra/host10/properties">
<property href="/discovery/v2/services/cassandra/host10/properties/cluster-name">
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property href="/discovery/v2/services/cassandra/host10/properties/contactpoint">
<key>contactpoint</key>
<value>10.0.0.10</value>
</property>
</properties>
</service>
</node>
<node node="host20" count="1" href="/discovery/v2/nodes/host20">
<service node="host20" service-class="cassandra" href="/discovery/v2/nodes/host20/cassandra">
<properties count="2" href="/discovery/v2/services/cassandra/host20/properties">
<property href="/discovery/v2/services/cassandra/host20/properties/cluster-name">
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property href="/discovery/v2/services/cassandra/host20/properties/contactpoint">
<key>contactpoint</key>
<value>10.0.0.20</value>
</property>
</properties>
</service>
</node>
</nodes>
<service-classes count="1" href="/discovery/v2/services">
<service-class service-class="cassandra" count="2" href="/discovery/v2/services/cassandra">
<service node="host10" service-class="cassandra" href="/discovery/v2/services/cassandra/host10">
<properties count="2" href="/discovery/v2/nodes/host10/cassandra/properties">
<property href="/discovery/v2/nodes/host10/cassandra/properties/cluster-name">
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property href="/discovery/v2/nodes/host10/cassandra/properties/contactpoint">
<key>contactpoint</key>
<value>10.0.0.10</value>
</property>
</properties>
</service>
<service node="host20" service-class="cassandra" href="/discovery/v2/services/cassandra/host20">
<properties count="2" href="/discovery/v2/nodes/host20/cassandra/properties">
<property href="/discovery/v2/nodes/host20/cassandra/properties/cluster-name">
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property href="/discovery/v2/nodes/host20/cassandra/properties/contactpoint">
<key>contactpoint</key>
<value>10.0.0.20</value>
</property>
</properties>
</service>
</service-class>
</service-classes>
</servicediscovery>In this sample XML there is only one service-class, namely cassandra; and there are two nodes, namely host10 and host20. As you can see, the logical global XML contains duplicate data: each unique service (identified by a service-class and a node) is listed twice: once grouped by node and once by service-class. Depending on the request URI a client can choose whether to focus on service-class or on node when querying the discovery API. Selecting which form to use depends on how you want to group the published services: if you are interested in the various instances of a specific service, use the service-class entry point as a basis. If you are interested in knowing which services are provided by a specific host, use the node entry point as a basis.
The explanation of specific API entry points in the various subsections will refer to parts of this logical XML. In sample XML snippets some content (such as the href attributes and irrelevant child elements) is omitted for the sake of brevity and readability. The following sections contain detailed information on how to use the Discovery Service web API.
Note
Syntax considerations
In the descriptions for the different API entry points you can see that certain service identifiers (namely service class, node and property key) can be used in request URI path segments and query parameters. It is therefore strongly advised to compose these identifiers from characters that can be correctly and unambiguously represented in such URIs. We recommend using only alphanumeric characters and dashes or underscores to separate name parts (as opposed to spaces, which would need escaping).
/discovery/v2/
GET List all services and nodes
Description
The query part can contain filters on service properties. Simply add the property name and value as key and value in the query part of the request.
Responses
200 The request was successful.
Examples
The response XML is similar to the snippet below (properties elements are omitted).
<servicediscovery>
<nodes count="2">
<node node="host10" count="1">
<service node="host10" service-class="cassandra">
...
</service>
</node>
<node node="host20" count="1">
<service node="host20" service-class="cassandra">
...
</service>
</node>
</nodes>
<service-classes count="1">
<service-class service-class="cassandra" count="2">
<service node="host10" service-class="cassandra">
...
</service>
<service node="host20" service-class="cassandra">
...
</service>
</service-class>
</service-classes>
</servicediscovery>
In this sample, there are two hosts running the same service.
When performing a request such as GET /discovery/v2?contactpoint=10.0.0.20 the result would be similar to the XML snippet below where only those services that have a property contactpoint with the value 10.0.0.20 are included in the result. <servicediscovery>
<nodes count="1">
<node node="host20" count="1">
<service node="host20" service-class="cassandra">
...
</service>
</node>
</nodes>
<service-classes count="1">
<service-class service-class="cassandra" count="1">
<service node="host20" service-class="cassandra">
...
</service>
</service-class>
</service-classes>
</servicediscovery>401 The client performed the request without authentication.
403 The client does not have the required discovery:read permission.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/nodes
GET List all nodes
Description
The query part can contain filters on service properties. Simply add the property name and value as key and value in the query part of the request.
Responses
200 The request was successful.
Examples
The response XML is similar to the snippet below (properties elements are omitted).
<nodes count="2">
<node node="host10" count="1">
<service node="host10" service-class="cassandra">
...
</service>
</node>
<node node="host20" count="1">
<service node="host20" service-class="cassandra">
...
</service>
</node>
</nodes>
In this sample, there are two hosts running the same service.401 The client performed the request without authentication.
403 The client does not have the required discovery:read permission.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/nodes/{node-name}
GET List all services provided by a specific node
Description
The query part can contain filters on service properties. Simply add the property name and value as key and value in the query part of the request.
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML is similar to the snippet below (properties elements are omitted) for a request to /discovery/v2/nodes/host10.
<nodes count="1">
<node node="host10" count="1">
<service node="host10" service-class="cassandra">
...
</service>
</node>
</nodes>
In this sample, there is only one service running on the selected host10.401 The client performed the request without authentication.
403 The client does not have the required discovery:read permission.
404 The specified node does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/nodes/{node-name}/{service-class}
GET Work with a specific service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
| service-class | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML for GET operations is similar to the snippet below for a request to /discovery/v2/nodes/host10/cassandra.
The responses for these two requests will only vary in the value of the href attributes (omitted in the snippet).
<service node="host10" service-class="cassandra">
<properties count="2">
<property>
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property>
<key>contactpoint</key>
<value>10.0.0.10</value>
</property>
</properties>
</service>
In this sample, the service identified by node host10 and service-class cassandra has two properties: cluster-name and contactpoint.401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
PUT Work with a specific service instance
Description
X-ID-Discovery-TTL for successful PUT operations (create new service or update existing service).
The value of this header corresponds to the Server’s /config/server/discovery/valid configuration setting.
It can be used by clients to determine how often the published service’s existence should be renewed to prevent the Server marking the service as ‘inactive’.
The request XML for PUT operations is identical to that returned by a GET operation. Clients need not specify href or count attributes; these will be ignored by the service.
Note
When updating an existing service the properties you specify in the request will replace those previously set. So properties that should stay unaltered must be explicitly specified in a PUT request to update a service, otherwise they are removed.
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
| service-class | path |
|
String |
Responses
200 The (update existing service) request was successful.
201 The (create new service) request was successful.
400 The request did not specify a body, or specified an invalid body.
401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
DELETE Work with a specific service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
| service-class | path |
|
String |
Responses
204 The request was successful.
401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/nodes/{node-name}/{service-class}/properties
GET List the properties of a specific service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
| service-class | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML is similar to the snippet below for a request to /discovery/v2/nodes/host10/cassandra/properties.
The responses for these two requests will only vary in the value of the href attributes (omitted in the snippet).
<properties count="2">
<property>
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property>
<key>contactpoint</key>
<value>10.0.0.10</value>
</property>
</properties>
In this sample, the service identified by node host10 and service-class cassandra has two properties: cluster-name and contactpoint.401 The client performed the request without authentication.
403 The client does not have the required discovery:read permission.
404 The specified service (class and/or node) not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/nodes/{node-name}/{service-class}/properties/{property-key}
GET Work with a specific property of a service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
| service-class | path |
|
String |
| property-key | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML for GET operations is similar to the snippet below for a request to /discovery/v2/nodes/host10/cassandra/properties/cluster-name.
The responses for these two requests will only vary in the value of the href attributes (omitted in the snippet).
<property>
<key>cluster-name</key>
<value>testcluster</value>
</property>
In this sample, the property identified by node host10, service-class cassandra and property key cluster-name has the value testcluster.401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) or the property does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
PUT Work with a specific property of a service instance
Description
The request XML for PUT operations is identical to that returned by a GET operation. Clients need not specify an href; this will be ignored by the service.
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
| service-class | path |
|
String |
| property-key | path |
|
String |
Responses
200 The (update existing property) request was successful.
201 The (create new property) request was successful.
400 The request did not specify a body, or specified an invalid body.
401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) or the property does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
DELETE Work with a specific property of a service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| node-name | path |
|
String |
| service-class | path |
|
String |
| property-key | path |
|
String |
Responses
204 The request was successful.
401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) or the property does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/services
GET List all services
Description
The query part can contain filters on service properties. Simply add the property name and value as key and value in the query part of the request.
Responses
200 The request was successful.
Examples
The response XML is similar to the snippet below (properties elements are omitted).
<service-classes count="1">
<service-class service-class="cassandra" count="2">
<service node="host10" service-class="cassandra">
...
</service>
<service node="host20" service-class="cassandra">
...
</service>
</service-class>
</service-classes>
In this sample, there are two hosts running the same service.401 The client performed the request without authentication.
403 The client does not have the required discovery:read permission.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/services/{service-class}
GET List all nodes on which a given service is available
Description
The query part can contain filters on service properties. Simply add the property name and value as key and value in the query part of the request.
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML is similar to the snippet below (properties elements are omitted) for a request to /discovery/v2/services/cassandra.
<service-classes count="1">
<service-class service-class="cassandra" count="2">
<service node="host10" service-class="cassandra">
...
</service>
<service node="host20" service-class="cassandra">
...
</service>
</service-class>
</service-classes>
In this sample, there are two hosts running the cassandra service.401 The client performed the request without authentication.
403 The client does not have the required discovery:read permission.
404 The specified service class does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/services/{service-class}/{node-name}
GET Work with a specific service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
| node-name | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML for GET operations is similar to the snippet below for a request to /discovery/v2/services/cassandra/host10.
The responses for these two requests will only vary in the value of the href attributes (omitted in the snippet).
<service node="host10" service-class="cassandra">
<properties count="2">
<property>
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property>
<key>contactpoint</key>
<value>10.0.0.10</value>
</property>
</properties>
</service>
In this sample, the service identified by node host10 and service-class cassandra has two properties: cluster-name and contactpoint.401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
PUT Work with a specific service instance
Description
X-ID-Discovery-TTL for successful PUT operations (create new service or update existing service).
The value of this header corresponds to the Server’s /config/server/discovery/valid configuration setting.
It can be used by clients to determine how often the published service’s existence should be renewed to prevent the Server marking the service as ‘inactive’.
The request XML for PUT operations is identical to that returned by a GET operation. Clients need not specify href or count attributes; these will be ignored by the service.
Note
When updating an existing service the properties you specify in the request will replace those previously set. So properties that should stay unaltered must be explicitly specified in a PUT request to update a service, otherwise they are removed.
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
| node-name | path |
|
String |
Responses
200 The (update existing service) request was successful.
201 The (create new service) request was successful.
400 The request did not specify a body, or specified an invalid body.
401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
DELETE Work with a specific service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
| node-name | path |
|
String |
Responses
204 The request was successful.
401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/services/{service-class}/{node-name}/properties
GET List the properties of a specific service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
| node-name | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML is similar to the snippet below for a request to /discovery/v2/services/cassandra/host10/properties.
The responses for these two requests will only vary in the value of the href attributes (omitted in the snippet).
<properties count="2">
<property>
<key>cluster-name</key>
<value>testcluster</value>
</property>
<property>
<key>contactpoint</key>
<value>10.0.0.10</value>
</property>
</properties>
In this sample, the service identified by node host10 and service-class cassandra has two properties: cluster-name and contactpoint.401 The client performed the request without authentication.
403 The client does not have the required discovery:read permission.
404 The specified service (class and/or node) not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
/discovery/v2/services/{service-class}/{node-name}/properties/{property-key}
GET Work with a specific property of a service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
| node-name | path |
|
String |
| property-key | path |
|
String |
Responses
200 The request was successful.
Examples
The response XML for GET operations is similar to the snippet below for a request to /discovery/v2/services/cassandra/host10/properties/cluster-name.
The responses for these two requests will only vary in the value of the href attributes (omitted in the snippet).
<property>
<key>cluster-name</key>
<value>testcluster</value>
</property>
In this sample, the property identified by node host10, service-class cassandra and property key cluster-name has the value testcluster.401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) or the property does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
PUT Work with a specific property of a service instance
Description
The request XML for PUT operations is identical to that returned by a GET operation. Clients need not specify an href; this will be ignored by the service.
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
| node-name | path |
|
String |
| property-key | path |
|
String |
Responses
200 The (update existing property) request was successful.
201 The (create new property) request was successful.
400 The request did not specify a body, or specified an invalid body.
401 The client performed the request without authentication.
403 The client does not have the required discovery:read or discovery:write permission.
404 The specified service (class and/or node) or the property does not exist.
500 Possible database connection problem. Check the Server log for more information.
Permissions
DELETE Work with a specific property of a service instance
Parameters
| Name | Located in | Description | Type |
|---|---|---|---|
| service-class | path |
|
String |
| node-name | path |
|
String |
| property-key | path |
|
String |