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:

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:

[
    {
        "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:

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:

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:

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:

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"}`