Use the CDAP Preferences Microservices to save, retrieve, and delete preferences in CDAP. Preferences, usage, and examples of using them, are described in Preferences and Runtime Arguments.

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.

Set Preferences

To set preferences for the CDAP instance, namespace, application, or program, submit an HTTP PUT request:

PUT /v3/preferences/
PUT /v3/namespaces/<namespace-id>/preferences
PUT /v3/namespaces/<namespace-id>/apps/<app-id>/preferences
PUT /v3/namespaces/<namespace-id>/apps/<app-id>/<program-type>/<program-id>/preferences

Parameter

Description

namespace-id

Namespace ID.

app-id

Name of application.

program-type

One of mapreduce, spark, workflows, services, or workers.

program-id

Name of program.

Properties, as a map of string-string pairs, are passed in the JSON request body.

Preferences can be set only for entities that exist. For example, preferences cannot be set for a namespace that does not exist or an application that has not yet been deployed.

HTTP Responses

Status Codes

Description

200 OK

The event successfully called the method, and the preferences were set/

400 BAD REQUEST

The JSON body has an invalid format.

404 NOT FOUND

The entity for which preferences are being set was not found.

Get Preferences

To retrieve the current preferences, issue an HTTP GET request:

GET /v3/preferences/
GET /v3/namespaces/<namespace-id>/preferences
GET /v3/namespaces/<namespace-id>/apps/<app-id>/preferences
GET /v3/namespaces/<namespace-id>/apps/<app-id>/<program-type>/<program-id>/preferences

This will return a JSON String map of the preferences:

{"key1": "value1", "key2": "value2"}

To retrieve the resolved preferences (collapsing preferences from higher levels into a single level), set the resolved query parameter to true:

GET /v3/preferences?resolved=true
GET /v3/namespaces/<namespace-id>/preferences?resolved=true
GET /v3/namespaces/<namespace-id>/apps/<app-id>/preferences?resolved=true
GET /v3/namespaces/<namespace-id>/apps/<app-id>/<program-type>/<program-id>/preferences?resolved=true

Parameter

Description

namespace-id

Namespace ID.

app-id

Name of application.

program-type

One of mapreduce, spark, workflows, services, or workers.

program-id

Name of program.

HTTP Responses

Status Codes

Description

200 OK

The event successfully called the method, and the preferences were retrieved.

404 NOT FOUND

The entity for which preferences are being set was not found.

Delete Preferences

To delete preferences, issue an HTTP DELETE. Preferences can be deleted only at one level with each request:

DELETE /v3/preferences/
DELETE /v3/namespaces/<namespace-id>/preferences
DELETE /v3/namespaces/<namespace-id>/apps/<app-id>/preferences
DELETE /v3/namespaces/<namespace-id>/apps/<app-id>/<program-type>/<program-id>/preferences

Parameter

Description

namespace-id

Namespace ID.

app-id

Name of application.

program-type

One of mapreduce, spark, workflows, services, or workers.

program-id

Name of program.

HTTP Responses

Status Codes

Description

200 OK

The event successfully called the method, and the preferences were deleted.

404 NOT FOUND

The entity for which preferences are being deleted was not found.