Service Microservices

Use the CDAP Service Microservices to list all services and making requests to the methods of an application’s services. See the Lifecycle Microservices for how to control the lifecycle of services.

For system services, see the Monitor Microservices and its methods.

Additional details and examples are found in the Services.

All methods or endpoints described in this API have a base URL (typically http://<host>:11015 or https://<host>:10443) that precedes the resource identifier, as described in the Microservices Conventions. These methods return a status code, as listed in the Microservices Status Codes.

Listing all Services

You can list all services in a namespace in CDAP by issuing an HTTP GET request to the URL:

1 GET /v3/namespaces/<namespace-id>/services

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

The response body will contain a JSON-formatted list of the existing services:

1 2 3 4 5 6 7 8 9 10 [ { "app": "PurchaseHistory", "description": "Service to retrieve Product IDs.", "id": "CatalogLookup", "name": "CatalogLookup", "type": "Service" } ... ]

Checking Service Availability

Once a service is started, you can can check whether the service is ready to accept service method requests by issuing an HTTP GET request to the URL:

1 GET /v3/namespaces/<namespace-id>/apps/<app-id>/services/<service-id>/available

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

app-id

Name of the application

service-id

Name of the service whose availability needs to be checked

HTTP Responses

Status Codes

Description

Status Codes

Description

503 Service Unavailable

The service is unavailable to take requests at the moment. For example, it might not have been started, or if the service has been started, it might not have become available yet to take requests.

200 OK

Service is ready to accept requests.

Note that when the service availability check returns 200, it is expected that calling the service methods will work. However, there is still a possibility for a service method call to fail; for example, if the service fails just after the availability call returns. It is highly recommended that error conditions (a 503 status code) be handled when making requests to service methods simply by retrying the request.

Checking Service Availability for a Program (Spark)

To list the availability status of a service:

1 GET /v3/namespaces/<namespace-id>/apps/<app-id>/<service-type>/<program-id>/available

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

app-id

Name of the application being called

program-type

Only “spark” and “services” service types are supported

program-id

Name of the program being called

Checking Service Availability for a Program (Spark)

To list the availability status of a service:

1 GET /v3/namespaces/<namespace-id>/apps/<app-id>/versions/<app-version>/<service-type>/program-id>/available

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

app-id

Name of the application being called

app-version

Application version

program-type

Only “spark” and “services” service types are supported

program-id

Name of the program being called

Requesting Service Methods

To make a request to a service's method, send the value of the method's @Path annotation as part of the request URL along with any additional headers, body, and query parameters.

The request type is defined by the service's method:

1 <request-type> /v3/namespaces/<namespace-id>/apps/<app-id>/services/<service-id>/methods/<endpoint-path>

Note: Any reserved or unsafe characters in the path parameters should be encoded using percent-encoding. See the section on Path Parameters for suggested approaches to encoding parameters.

Parameter

Description

Parameter

Description

namespace-id

Namespace ID

request-type

One of GET, POST, PUT, or DELETE. This is defined by the handler method.

app-id

Name of the application being called

service-id

Name of the service being called

endpoint-path

Endpoint path of the method being called

HTTP Responses

Status Codes

Description

Status Codes

Description

503 Service Unavailable

The service is unavailable. For example, it may not yet have been started.

Other responses are defined by the service's method.

Example

HTTP Method

GET /v3/namespaces/default/apps/WordCount/services/RetrieveCounts/methods/count/Cask?limit=2

Description

Make a request to the count/{word} endpoint of the RetrieveCounts service in the application WordCount in the namespace default to get a count of the word "Cask" and its associated words with a limit of 2.

Response Status Code

200 OK

Response Body

{ "assocs": { "CaskData": 1, "CaskInc": 1 }, "count": 5, "word": "Cask"}