Namespace HTTP RESTful API

Use the CDAP Namespace HTTP RESTful API to create, list, and delete namespaces in the CDAP instance.

Namespaces, their use and examples, are described in the Developer Manual: Namespaces.

The definition of namespace names supported by this API is described under Names and Characters for Namespace Identifiers.

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.

Create a Namespace

To create a namespace, submit an HTTP PUT request:

PUT /v3/namespaces/<namespace-id>
Parameter Description
namespace-id Namespace

The namespace-id must be of the limited character set for namespaces, as described in the Introduction. Properties for the namespace are passed in the JSON request body:

Parameter Description Default Value (if not defined)
description Display description of the namespace An empty string ("")
config Configuration preferences for the namespace A JSON string of configuration key-value pairs

If a namespace with the same name already exists, the method will still return 200 OK, but with a message that the Namespace '<namespace-id>' already exists.

HTTP Responses

Status Codes Description
200 OK The event successfully called the method, and the namespace was created

List Existing Namespaces

To list all of the existing namespaces, issue an HTTP GET request:

GET /v3/namespaces

This will return a JSON String map that lists each namespace with its name and description (reformatted to fit):

[{"name": "default", "description": "Default Namespace", "config": {"scheduler.queue.name": ""}},
 {"name": "demo_namespace", "description": "My Demo Namespace", "config": {"scheduler.queue.name": "demo"}}]

Details of a Namespace

For detailed information on a specific namespace, use:

GET /v3/namespaces/<namespace-id>

The information (namespace, description, config) will be returned in the body of the response, such as:

{"name":"default","description":"Default Namespace","config":{"scheduler.queue.name":""}}
Parameter Description
namespace-id Namespace

HTTP Responses

Status Codes Description
200 OK The event successfully called the method, and the body contains the results

Editing a Namespace

To edit an existing namespace, submit an HTTP PUT request to:

PUT /v3/namespaces/<namespace-id>/properties
Parameter Description
namespace-id Namespace

The namespace-id must be the name of an existing namespace. Properties for the namespace are passed in the JSON request body, as described for when you Create a Namespace.

Property Description
description Display description of the namespace
config Configuration properties, with a JSON map of key-value pairs.

HTTP Responses

Status Codes Description
200 OK Namespace properties were changed successfully
400 Bad Request The request was not created correctly
404 Not Found The Namespace does not exist

Example

HTTP Method

PUT /v3/namespaces/dev/properties:

{
  "description": "Namespace for development of applications",
  "config": {
    "scheduler.queue.name": "A",
  },
}
Description Set the description property of the Namespace named dev, and set the scheduler.queue.name to A.

Deleting a Namespace

To delete an existing namespace (including all applications, streams, flows, datasets, metrics, and other components), submit an HTTP DELETE request to:

DELETE /v3/unrecoverable/namespaces/<namespace-id>
Parameter Description
namespace-id Namespace

To prevent accidental use of this method, it will only work if the cdap-site.xml parameter enable.unrecoverable.reset has been enabled. This method must be exercised with extreme caution, as there is no recovery from it.

Both the CDAP CLI and the CDAP UI expose this function; they also require the parameter to be enabled in order for their functions to work.

In the case of the default namespace, after everything has been deleted, the default namespace is retained, as it is always available in CDAP.

To delete only the datasets of a namespace, there is a specific dataset endpoint for that.

Namespace Configurations

When creating or editing a namespace, namespace configurations can be supplied as part of the request body. These are in the form of a JSON string of configuration key-value pairs. Note that the values for these keys cannot be modified once the namespace has been created, with the exception of the property scheduler.queue.name.

Namespace Configurations

Configuration Name Description
hbase.namespace The pre-existing HBase namespace to be used for the namespace (CDAP Distributed mode only)
hive.database The pre-existing Hive database to be used for the namespace
keytabURI The URI of the Kerberos keytab file for the namespace
principal The Kerberos principal for the namespace
groupName The group name for the namespace. If present, the namespace's data directory is created with this group name, and read, write, and execute permissions are given to the group. The namespace principal must be a member of this group.
root.directory The pre-existing file-system directory to be used for the namespace
scheduler.queue.name Scheduler queue for CDAP programs and CDAP explore queries run in the namespace. See Scheduler queue for details.