๐Ÿ”—Views HTTP RESTful API

Use the CDAP Views HTTP RESTful API to create, list, detail, and delete stream views.

Views are a read-only source from where data can be read. They are similar to a stream or dataset.

A view has a specific read format. Read formats consist of a format (such as CSV, TSV, or Avro, amongst others) and a schema. Some formats (CSV, TSV) use an additional settings attribute to complete the mapping of data to fields.

CDAP Explore needs to be enabled before any views are created so that a Hive table can be created for each view. (See the CDAP installation instructions for your particular Hadoop distribution for details.)

Currently, views are only supported for streams. Support for datasets will be added in a later version of CDAP.

Additional details are found in the Developers' Manual: Views.

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.

๐Ÿ”—Creating a Stream View

A view can be added to an existing stream with an HTTP POST request to the URL:

PUT /v3/namespaces/<namespace-id>/streams/<stream-id>/views/<view-id>
Parameter Description
namespace-id Namespace ID
stream-id Name of the stream (must be already existing)
view-id Name of the view to be created, or, if already existing, updated

The request body is a JSON object specifying the read format to be used.

An existing stream view can be modified with the same command; only the response code will differ.

Example

For example, to create a stream view logStreamView on an existing stream logStream, using the format clf and a schema, you could use (reformatted for display):

$ curl -w"\n" -X PUT "http://example.com:11015/v3/namespaces/default/streams/logStream/views/logStreamView" \
  -H 'Content-Type: application/json' -d \
  "{
    'format': {
      'name': 'clf',
      'schema':
        '{
          \'type\':\'record\',
          \'name\':\'event\',
          \'fields\':[
            {\'name\':\'remotehost\',\'type\':\'string\'},
            {\'name\':\'rfc931\',\'type\':\'string\'},
            {\'name\':\'authuser\',\'type\':\'string\'},
            {\'name\':\'date\',\'type\':\'date\'},
            {\'name\':\'request\',\'type\':\'string\'},
            {\'name\':\'status\',\'type\':\'string\'},
            {\'name\':\'bytes\',\'type\':\'int\'}
        ]}',
      'settings': {
        'key1':'val1',
        'key2':'val2'
      }
    }
  }"
> curl -X PUT "http://example.com:11015/v3/namespaces/default/streams/logStream/views/logStreamView" ^
  -H 'Content-Type: application/json' -d ^
  "{
    'format': {
      'name': 'clf',
      'schema':
        "{
          \'type\':\'record\',
          \'name\':\'event\',
          \'fields\':[
            {\'name\':\'remotehost\',\'type\':\'string\'},
            {\'name\':\'rfc931\',\'type\':\'string\'},
            {\'name\':\'authuser\',\'type\':\'string\'},
            {\'name\':\'date\',\'type\':\'date\'},
            {\'name\':\'request\',\'type\':\'string\'},
            {\'name\':\'status\',\'type\':\'string\'},
            {\'name\':\'bytes\',\'type\':\'int\'}
        ]}',
      'settings': {
        'key1':'val1',
        'key2':'val2'
      }
    }
  }\"

HTTP Responses

Status Codes Description
200 OK An existing stream view was successfully modified
201 CREATED A new stream view was created

๐Ÿ”—Listing Stream Views

To list all of the existing stream views of an existing stream, issue an HTTP GET request to the URL:

GET /v3/namespaces/<namespace-id>/streams/<stream-id>/views
Parameter Description
namespace-id Namespace ID
stream-id Name of the stream (must be already existing)

The response body is a JSON object with a list of all the views currently existing for the specified stream.

Example

For example, to see all the stream views on an existing stream logStream, you could use:

$ curl -w"\n" -X GET "http://example.com:11015/v3/namespaces/default/streams/logStream/views"

["logStreamView1", "logStreamView2", ...]
> curl -X GET "http://example.com:11015/v3/namespaces/default/streams/logStream/views"

["logStreamView1", "logStreamView2", ...]

HTTP Responses

Status Codes Description
200 OK A list of stream views for the specified stream was successfully retrieved
404 Not Found The specified stream was not found

๐Ÿ”—Details of a Stream View

For detailed information on an existing stream view, issue an HTTP GET request to the URL:

GET /v3/namespaces/<namespace-id>/streams/<stream-id>/views/<view-id>
Parameter Description
namespace-id Namespace ID
stream-id Name of the stream
view-id Name of the existing view

Example

For example, to see the details of the stream view logStreamView on the stream logStream, you could use (results pretty-printed for display):

$ curl -w"\n" -X GET "http://example.com:11015/v3/namespaces/default/streams/logStream/view/logStreamView"

{"id":"logStreamView",
 "format":
    {"name":"clf",
     "schema":
        {"type":"record",
         "name":"event",
         "fields":[{"name":"remotehost","type":["string","not-null"]},...],
         "settings":{...}
        }
    },
 "tableName":"stream_logStream_logStreamView"
}
> curl -X GET "http://example.com:11015/v3/namespaces/default/streams/logStream/view/logStreamView"

{"id":"logStreamView",
 "format":
    {"name":"clf",
     "schema":
        {"type":"record",
         "name":"event",
         "fields":[{"name":"remotehost","type":["string","not-null"]},...],
         "settings":{...}
        }
    },
 "tableName":"stream_logStream_logStreamView"
}

HTTP Responses

Status Codes Description
200 OK A JSON object describing the specified stream view was successfully retrieved
404 Not Found Either the specified stream view or the specified stream was not found

๐Ÿ”—Deleting a Stream View

To delete an existing stream view, issue an HTTP DELETE request to the URL:

DELETE /v3/namespaces/<namespace-id>/streams/<stream-id>/views/<view-id>
Parameter Description
namespace-id Namespace ID
stream-id Name of the stream
view-id Name of the existing view

Example

For example, to delete the stream view logStreamView on the stream logStream, you could use:

$ curl -w"\n" -X DELETE "http://example.com:11015/v3/namespaces/default/streams/logStream/view/logStreamView"
> curl -X DELETE "http://example.com:11015/v3/namespaces/default/streams/logStream/view/logStreamView"

HTTP Responses

Status Codes Description
200 OK The specified stream view was successfully deleted
404 Not Found Either the specified stream view or the specified stream was not found