Service HTTP RESTful API

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

For system services, see the Monitor HTTP RESTful API and its methods.

See the Route Config HTTP RESTful API for allocating requests between different versions of a service.

Additional details and examples are found in the Developer Manual: 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 RESTful API Conventions. These methods return a status code, as listed in the RESTful API 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
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
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
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.

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:

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