Analytics Links REST API

    +

    Overview

    The Analytics Links REST API is provided by the Analytics service. This API enables you to manage the links to remote Couchbase clusters and external data sources.

    The API schemes and host URLs are as follows:

    • http://node:8095/

    • https://node:18095/ (for secure access)

    where node is the host name or IP address of a node running the Analytics service.

    Version information

    Version : 6.6

    Consumes

    • application/x-www-form-urlencoded

    Produces

    • application/json

    Paths

    Table of Contents

    POST /analytics/link

    Description

    Creates a link.

    When creating or altering a remote link using an alternate address, note the following:

    • At least one node in the remote cluster must expose the mgmt port (rest_port, default 8091) or the mgmtSSL port (ssl_rest_port, default 18091).

    • Furthermore, all data nodes in the remote cluster must expose the kv port (memcached_port, default 11210) or the kvSSL port (memcached_ssl_port, default 11207).

    Failure to do so will result in a 400 (Bad Request) error.

    The SSL ports are required when the encryption mode is set to full; the non-SSL ports are required otherwise.
    When creating a link to the Amazon S3 service, be sure to follow best practices for security. AWS root account credentials should never be used. The policy for the created IAM User roles should be as strict as possible and only allow access to the required data and required resources. You only need to know the Access Key Id and the Secret Access Key for the created IAM User role to access the S3 service. The link will be able to access whatever is permitted to the IAM User, since it will be using the IAM User credentials to interact with the AWS S3 service.

    Parameters

    Type Name Description Schema

    FormData

    dataverse
    required

    The name of the dataverse containing the link.

    string

    FormData

    name
    required

    The name of the link.

    string

    FormData

    type
    required

    The type of the link.

    couchbase: A link to a remote Couchbase cluster.
    s3: A link to the Amazon S3 service.

    enum (s3, couchbase)

    FormData

    hostname
    required

    For Couchbase links only. The remote hostname.

    string

    FormData

    encryption
    required

    For Couchbase links only. The type of encryption used by the link.

    none: Neither passwords nor data are encrypted.
    half: Passwords are encrypted using SCRAM-SHA, but data is not.
    full: All data and passwords are encrypted and TLS is used.

    enum (none, half, full)

    FormData

    username
    optional

    For Couchbase links only. The remote username. Required for links with no encryption or half encryption. Required for links with full encryption if using a password.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    password
    optional

    For Couchbase links only. The remote password. Required for links with no encryption or half encryption. Required for links with full encryption if using a username.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    certificate
    optional

    For Couchbase links only. The content of the target cluster root certificate. Required for links with full encryption.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    clientCertificate
    optional

    For Couchbase links only. The content of the client certificate. Required for links with full encryption if using a client key.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    clientKey
    optional

    For Couchbase links only. The content of the client key. Required for links with full encryption if using a client certificate.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    accessKeyId
    required

    For S3 links only. The Amazon S3 access key ID.

    string

    FormData

    secretAccessKey
    required

    For S3 links only. The Amazon S3 secret access key.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    region
    required

    For S3 links only. The Amazon S3 region.

    string

    FormData

    serviceEndpoint
    optional

    For S3 links only. The Amazon S3 service endpoint.

    string

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. A parameter has an incorrect value.

    Errors

    500

    Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

    Errors

    Security

    Type Name

    basic

    Analytics Manage

    Example HTTP request

    The example below creates a Couchbase link named myCbLink in the Default dataverse, with no encryption.

    Curl request

    $ curl -v -u Administrator:password \
           -X POST http://localhost:8095/analytics/link \
           -d dataverse=Default \
           -d name=myCbLink \
           -d type=couchbase \
           -d hostname=remoteHostName:8091 \
           -d encryption=none \
           --data-urlencode username=remote.user \
           --data-urlencode password=remote.p4ssw0rd
    The username and password parameters are URL-encoded to escape any special characters.

    The example below creates an Amazon S3 link named myAwsLink in the Default dataverse.

    Curl request

    $ curl -v -u Administrator:password \
           -X POST http://localhost:8095/analytics/link \
           -d dataverse=Default \
           -d name=myAwsLink \
           -d type=s3 \
           -d region=us-east-1 \
           -d accessKeyId=myAccessKey \
           --data-urlencode secretAccessKey=mySecretKey
    The secretAccessKey parameter is URL-encoded to escape any special characters.

    GET /analytics/link

    Description

    Returns information about the specified link or links.

    Parameters

    Type Name Description Schema

    Query

    dataverse
    optional

    The name of the dataverse containing the link. If this parameter is omitted, all dataverses are queried for links.

    string

    Query

    name
    optional

    The name of the link. If this parameter is specified, the dataverse name must be specified also. If this parameter is omitted, all links will be retrieved from the specified dataverses.

    string

    Query

    type
    optional

    The type of the link. If this parameter is omitted, all link types are retrieved, excluding the Local link.

    enum (S3, couchbase)

    Responses

    HTTP Code Description Schema

    200

    Success. Returns an array of objects, each of which contains information about a link.

    < Links > array

    400

    Bad request. A parameter has an incorrect value.

    Errors

    500

    Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

    Errors

    Security

    Type Name

    basic

    Analytics Manage

    Example HTTP request

    The example below queries all links in the Default dataverse.

    Curl request

    $ curl -v -u Administrator:password \
           http://localhost:8095/analytics/link?dataverse=Default

    Example HTTP response

    Response 200

    [ {
      "accessKeyId" : "myAccessKey",
      "dataverse" : "Default",
      "name" : "myAwsLink",
      "region" : "us-east-1",
      "secretAccessKey" : "<redacted sensitive entry>",
      "serviceEndpoint" : null,
      "type" : "s3"
    }, {
      "activeHostname" : "remoteHostName:8091",
      "bootstrapAlternateAddress" : false,
      "bootstrapHostname" : "remoteHostName:8091",
      "certificate" : null,
      "clientCertificate" : null,
      "clientKey" : null,
      "clusterCompatibility" : 393221,
      "dataverse" : "Default",
      "encryption" : "none",
      "name" : "myCbLink",
      "nodes" : [ {
        "alternateAddresses" : null,
        "hostname" : null,
        "services" : {
          "cbas" : 8095,
          "cbasSSL" : 18095,
          "kv" : 11210,
          "kvSSL" : 11207,
          "mgmt" : 8091,
          "mgmtSSL" : 18091
        }
      } ],
      "password" : "<redacted sensitive entry>",
      "type" : "couchbase",
      "username" : "remote.user",
      "uuid" : "6331e2a390125b662f7bcfd63ecb3a73"
    } ]

    PUT /analytics/link

    Description

    Edits an existing link with the provided information. The link name, type, and dataverse name cannot be modified.

    Parameters

    Type Name Description Schema

    FormData

    dataverse
    required

    The name of the dataverse containing the link.

    string

    FormData

    name
    required

    The name of the link.

    string

    FormData

    type
    optional

    The type of the link. If this parameter is specified, the value must match the type that was set when the link was created.

    enum (s3, couchbase)

    FormData

    hostname
    required

    For Couchbase links only. The remote hostname.

    string

    FormData

    encryption
    required

    For Couchbase links only. The type of encryption used by the link.

    none: Neither passwords nor data are encrypted.
    half: Passwords are encrypted using SCRAM-SHA, but data is not.
    full: All data and passwords are encrypted and TLS is used.

    enum (none, half, full)

    FormData

    username
    optional

    For Couchbase links only. The remote username. Required for links with no encryption or half encryption. Required for links with full encryption if using a password.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    password
    optional

    For Couchbase links only. The remote password. Required for links with no encryption or half encryption. Required for links with full encryption if using a username.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    certificate
    optional

    For Couchbase links only. The content of the target cluster root certificate. Required for links with full encryption.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    clientCertificate
    optional

    For Couchbase links only. The content of the client certificate. Required for links with full encryption if using a client key.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    clientKey
    optional

    For Couchbase links only. The content of the client key. Required for links with full encryption if using a client certificate.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    accessKeyId
    required

    For S3 links only. The Amazon S3 access key ID.

    string

    FormData

    secretAccessKey
    required

    For S3 links only. The Amazon S3 secret access key.

    You should URL-encode this parameter to escape any special characters.

    string

    FormData

    region
    required

    For S3 links only. The Amazon S3 region.

    string

    FormData

    serviceEndpoint
    optional

    For S3 links only. The Amazon S3 service endpoint.

    string

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. A parameter has an incorrect value.

    Errors

    500

    Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

    Errors

    Security

    Type Name

    basic

    Analytics Manage

    Example HTTP request

    The example below edits the link named myCbLink in the Default dataverse to use full encryption with a client certificate and client key.

    Curl request

    $ curl -v -u Administrator:password \
           -X PUT http://localhost:8095/analytics/link \
           -d dataverse=Default \
           -d name=myCbLink \
           -d type=couchbase \
           -d hostname=remoteHostName:8091 \
           -d encryption=full \
           --data-urlencode "certificate=$(cat ./cert/targetClusterRootCert.pem)" \
           --data-urlencode "clientCertificate=$(cat ./cert/clientCert.pem)" \
           --data-urlencode "clientKey=$(cat ./cert/client.key)"
    The certificate, clientCertificate, and clientKey parameters use command substitution with the cat command to return the content of the referenced files. The content of these files is then URL-encoded to escape any special characters.

    DELETE /analytics/link

    Description

    Deletes a link using the provided parameters. The link cannot be deleted if any other entities, such as datasets, are using it. The entities using the link need to be disconnected from the link, otherwise, the delete operation fails.

    Parameters

    Type Name Description Schema

    FormData

    dataverse
    required

    The name of the dataverse containing the link.

    string

    FormData

    name
    required

    The name of the link.

    string

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. A parameter has an incorrect value.

    Errors

    500

    Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.

    Errors

    Security

    Type Name

    basic

    Analytics Manage

    Example HTTP request

    The example below deletes the link named myCbLink from the Default dataverse.

    Curl request

    $ curl -v -u Administrator:password \
           -X DELETE http://localhost:8095/analytics/link \
           -d dataverse=Default \
           -d name=myCbLink

    The example below deletes the link named myAwsLink from the Default dataverse.

    Curl request

    $ curl -v -u Administrator:password \
           -X DELETE http://localhost:8095/analytics/link \
           -d dataverse=Default \
           -d name=myAwsLink

    Definitions

    Table of Contents

    These properties are common to all links.

    Name Description Schema

    dataverse
    required

    The name of the dataverse containing the link.
    Example : "Default"

    string

    name
    required

    The name of the link.
    Example : "myLink"

    string

    type
    required

    The type of the link.

    couchbase: A link to a remote Couchbase cluster.
    s3: A link to the Amazon S3 service.

    Different properties are returned, depending on the link type: refer to Couchbase or S3.

    enum (s3, couchbase)

    Couchbase

    These properties are returned for remote Couchbase links.

    Polymorphism : Inheritance
    Discriminator : type

    Name Description Schema

    dataverse
    required

    The name of the dataverse containing the link.
    Example : "Default"

    string

    name
    required

    The name of the link.
    Example : "myLink"

    string

    type
    required

    The type of the link.

    couchbase: A link to a remote Couchbase cluster.
    s3: A link to the Amazon S3 service.

    Different properties are returned, depending on the link type: refer to Couchbase or S3.

    enum (s3, couchbase)

    activeHostname
    required

    The remote hostname.
    Example : "remoteHostName:8091"

    string

    bootstrapAlternateAddress
    required

    Specifies whether the provided (bootstrap) hostname is an alternative address.
    Example : false

    boolean

    bootstrapHostname
    required

    The provided (bootstrap) hostname.
    Example : "remoteHostName:8091"

    string

    certificate
    required

    The content of the target cluster root certificate. Only set for links with full encryption. If not set, this property returns null.

    string

    clientCertificate
    required

    The content of the client certificate. Only set for links with full encryption using client certificate and client key. If not set, this property returns null.

    string

    clientKey
    required

    The content of the client key. Only set for links with full encryption using client certificate and client key. If not set, this property returns null.

    string

    clusterCompatibility
    required

    For internal use only.
    Example : 393221

    integer

    encryption
    required

    The type of encryption used by the link.

    none: Neither passwords nor data are encrypted.
    half: Passwords are encrypted using SCRAM-SHA, but data is not.
    full: All data and passwords are encrypted and TLS is used.

    enum (none, half, full)

    nodes
    required

    An array of objects, each of which contains information about a node in the target cluster.

    < Nodes > array

    password
    required

    The password used to connect to the link. This is redacted for the sake of security. Not set for links with full encryption using client certificate and client key. If not set, this property returns null.
    Example : "<redacted sensitive entry>"

    string

    username
    required

    The remote username. Not set for links with full encryption using client certificate and client key. If not set, this property returns null.
    Example : "remote.user"

    string

    uuid
    required

    A UUID uniquely identifying the link.
    Example : "6331e2a390125b662f7bcfd63ecb3a73"

    string (UUID)

    Nodes

    Name Description Schema

    alternateAddresses
    optional

    The alternate address defined on the node, if any. If not defined, this property returns null.

    string

    hostname
    optional

    The hostname of the node. If not defined, this property returns null.

    string

    services
    optional

    An object giving information about the services and ports configured on this node.

    Services

    Services

    Name Description Schema

    cbas
    optional

    The port number for a connection to the Analytics service.
    Example : 8095

    integer

    cbasSSL
    optional

    The port number for an encrypted connection to the Analytics service.
    Example : 18095

    integer

    kv
    optional

    The port number for a connection to the Data service.
    Example : 11210

    integer

    kvSSL
    optional

    The port number for an encrypted connection to the Data service.
    Example : 11207

    integer

    mgmt
    optional

    The port number for a connection to the Cluster Manager service.
    Example : 8091

    integer

    mgmtSSL
    optional

    The port number for an encrypted connection to the Cluster Manager service.
    Example : 18091

    integer

    S3

    These properties are returned for S3 links.

    Polymorphism : Inheritance
    Discriminator : type

    Name Description Schema

    dataverse
    required

    The name of the dataverse containing the link.
    Example : "Default"

    string

    name
    required

    The name of the link.
    Example : "myLink"

    string

    type
    required

    The type of the link.

    couchbase: A link to a remote Couchbase cluster.
    s3: A link to the Amazon S3 service.

    Different properties are returned, depending on the link type: refer to Couchbase or S3.

    enum (s3, couchbase)

    accessKeyId
    required

    The Amazon S3 access key ID.
    Example : "myAccessKey"

    string

    region
    required

    The Amazon S3 region.
    Example : "us-east-1"

    string

    secretAccessKey
    required

    The Amazon S3 secret access key. This is redacted for the sake of security.
    Example : "<redacted sensitive entry>"

    string

    serviceEndpoint
    required

    Amazon S3 service endpoint. If not set, this property returns null.
    Example : "myEndpointUri"

    string

    Errors

    Name Description Schema

    error
    required

    An error message.

    string

    Security

    Analytics Manage

    The Analytics Links REST API supports HTTP basic authentication. Credentials can be passed via HTTP headers.

    Users must have one of the following RBAC roles:

    • Full Admin

    • Cluster Admin

    • Analytics Admin

    Refer to Roles for more details.

    Type : basic