openapi: 3.0.3
info:
  title: Enterprise Analytics Links REST API
  version: '2.1'
  description: This API enables you to manage the links to remote Couchbase clusters and external data sources.
servers:
  - url: '{scheme}://{host}:{port}'
    description: The URL scheme, host, and port are as follows.
    variables:
      scheme:
        default: http
        description: |-
          The URL scheme.
          Use `https` for secure access.
        enum:
          - http
          - https
      host:
        default: localhost
        description: The host name or IP address of a node.
      port:
        default: '8095'
        description: |-
          The Enterprise Analytics Service REST port.
          Use `18095` for secure access.
        enum:
          - '8095'
          - '18095'
tags:
  - name: Single Links
    description: Operations for single links.
  - name: Multiple Links
    description: Operations for multiple links.
paths:
  /api/v1/link:
    get:
      operationId: get_all
      summary: Query All Links
      description: Returns information about all links
      tags:
        - Multiple Links
      security:
        - AnalyticsManage: []
        - DescribeLink: []
      responses:
        '200':
          description: |
            Success. Returns an array of objects, each of which contains information about a link.
          content:
            application/json:
              schema:
                type: array
                items:
                  title: Links
                  description: These properties are common to all links.
                  type: object
                  discriminator: &ref_7
                    propertyName: type
                    mapping:
                      couchbase: '#/components/schemas/ResponseCouchbase'
                      s3: '#/components/schemas/ResponseS3'
                      azureblob: '#/components/schemas/ResponseAzureBlob'
                  required: &ref_8
                    - name
                    - type
                  properties: &ref_9
                    name:
                      type: string
                      description: The name of the link.
                      x-has-example: true
                      example: myLink
                    type:
                      type: string
                      x-desc-name: type
                      description: |-
                        The type of the link.

                        * `couchbase`: A link to a remote Couchbase cluster.
                        * `s3`: A link to the Amazon S3 service.
                        * `azureblob`: A link to the Azure Blob Storage service.
                      enum:
                        - couchbase
                        - s3
                        - azureblob
        '400':
          description: |
            Bad request. A parameter has an incorrect value.
          content: &ref_4
            application/json:
              schema:
                title: Errors
                type: object
                required: &ref_0
                  - error
                properties: &ref_1
                  error:
                    type: string
                    description: An error message.
        '500':
          description: |
            Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.
          content: &ref_5
            application/json:
              schema:
                title: Errors
                type: object
                required: *ref_0
                properties: *ref_1
  /api/v1/link/{name}:
    post:
      operationId: post_link
      summary: Create Link
      description: Creates a link
      tags:
        - Single Links
      parameters:
        - name: name
          schema: &ref_6
            type: string
          in: path
          required: true
          description: The name of the link.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - title: Create Couchbase Link Request
                  allOf: &ref_19
                    - type: object
                      required: &ref_2
                        - type
                      properties: &ref_3
                        type:
                          title: Create Request Type
                          type: string
                          description: |-
                            The type of the link.

                            * `couchbase`: A link to a remote Couchbase cluster.
                            * `s3`: A link to the Amazon S3 service.
                            * `azureblob`: A link to the Azure Blob Storage service.
                          enum: &ref_18
                            - couchbase
                            - s3
                            - azureblob
                    - title: Couchbase Specific Request
                      type: object
                      required: &ref_11
                        - hostname
                        - encryption
                      properties: &ref_12
                        hostname:
                          type: string
                          description: |
                            For Couchbase links only. The remote hostname.
                        username:
                          type: string
                          description: |
                            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.
                        password:
                          type: string
                          description: |
                            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.
                        encryption:
                          type: string
                          description: |-
                            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
                        certificate:
                          type: string
                          description: |
                            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. If required, this parameter may contain multiple certificates, separated by new lines.
                        clientCertificate:
                          type: string
                          description: |-
                            For Couchbase links, this is 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.
                        clientKey:
                          type: string
                          description: |
                            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.
                - title: Create S3 Link Request
                  allOf: &ref_20
                    - type: object
                      required: *ref_2
                      properties: *ref_3
                    - title: S3 Specific Request
                      type: object
                      required: &ref_14
                        - region
                      properties: &ref_15
                        region:
                          type: string
                          description: |
                            For S3 links only. The Amazon S3 region.
                        accessKeyId:
                          type: string
                          description: |
                            For S3 links only. The Amazon S3 access key ID. Required when using access key authentication. Must be provided together with `secretAccessKey`.
                        secretAccessKey:
                          type: string
                          description: |
                            For S3 links only. The Amazon S3 secret access key. Required when using access key authentication. Must be provided together with `accessKeyId`.

                            You should URL-encode this parameter to escape any special characters.
                        sessionToken:
                          type: string
                          description: |
                            For S3 links only. The Amazon S3 session token. Use this parameter if you want the link to have temporary access. Requires `accessKeyId` and `secretAccessKey` to also be provided.

                            Passing this parameter indicates that the credentials are temporary. The Amazon S3 service validates the session token with each request to check whether the provided credentials have expired or are still valid.
                        instanceProfile:
                          type: string
                          enum:
                            - 'true'
                          description: |
                            For S3 links only. If set to `true`, the link uses the EC2 instance profile for authentication. Cannot be combined with `accessKeyId`, `secretAccessKey`, or `sessionToken`.
                        roleArn:
                          type: string
                          description: |
                            For S3 links only. The Amazon Resource Name (ARN) of the role to assume for cross-account authentication. Requires either `instanceProfile` or `accessKeyId` and `secretAccessKey` (non-temporary) to provide the credentials used to assume the role.
                        externalId:
                          type: string
                          description: |
                            For S3 links only. An external ID for cross-account role assumption. Used together with `roleArn`. If `roleArn` is provided and `externalId` is not, one is automatically generated and returned in the response.
                        crossRegion:
                          type: string
                          enum:
                            - 'true'
                            - 'false'
                          description: |
                            For S3 links only. If set to `true`, allows the link to access S3 buckets in regions other than the one specified by `region`. Warning: Accessing buckets in a different region incurs cross-region data transfer charges.
                        serviceEndpoint:
                          type: string
                          description: |
                            For S3 links only. The Amazon S3 service endpoint.
                        pathStyleAddressing:
                          type: string
                          enum:
                            - 'true'
                            - 'false'
                          description: |
                            For S3 links only. If set to `true`, uses path-style addressing for S3 requests instead of virtual-hosted-style. Defaults to `true` if `serviceEndpoint` is set.
                        disableSslVerify:
                          type: boolean
                          description: |
                            For S3 links only. If set to `true`, SSL verification is disabled.
                - title: Create Azure Blob Link Request
                  allOf: &ref_21
                    - type: object
                      required: *ref_2
                      properties: *ref_3
                    - title: Azure Blob Specific Request
                      type: object
                      required: &ref_16
                        - endpoint
                      properties: &ref_17
                        endpoint:
                          type: string
                          description: |-
                            The endpoint URI.

                            Required for Azure Blob links; optional for S3 links (e.g. when using S3-compatible storage).
                        accountName:
                          type: string
                          description: |
                            For Azure Blob links only. The account name. Used for shared key authentication.

                            You should URL-encode this parameter to escape any special characters.
                        accountKey:
                          type: string
                          description: |
                            For Azure Blob links only. The account key. Used for shared key authentication.

                            You should URL-encode this parameter to escape any special characters.
                        sharedAccessSignature:
                          type: string
                          description: |
                            For Azure Blob links only. A token that can be used for authentication. Used for shared access signature authentication.

                            You should URL-encode this parameter to escape any special characters.
                        disableSslVerify:
                          type: boolean
                          description: |
                            For Azure Blob links only. If set to `true`, SSL verification is disabled.
      security:
        - AnalyticsManage: []
        - CreateLink: []
      responses:
        '200':
          description: The operation was successful.
        '400':
          description: |
            Bad request. A parameter has an incorrect value.
          content: *ref_4
        '500':
          description: |
            Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.
          content: *ref_5
    get:
      operationId: get_link
      summary: Query Link
      description: Returns information about a link.
      tags:
        - Single Links
      parameters:
        - name: name
          schema: *ref_6
          in: path
          required: true
          description: The name of the link.
        - name: type
          in: query
          required: false
          schema:
            title: Edit Request Type
            type: string
            description: |
              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: &ref_10
              - couchbase
              - s3
              - azureblob
      security:
        - AnalyticsManage: []
        - DescribeLink: []
      responses:
        '200':
          description: |
            Success. Returns an array of objects, each of which contains information about a link.
          content:
            application/json:
              schema:
                type: array
                items:
                  title: Links
                  description: These properties are common to all links.
                  type: object
                  discriminator: *ref_7
                  required: *ref_8
                  properties: *ref_9
        '400':
          description: |
            Bad request. A parameter has an incorrect value.
          content: *ref_4
        '500':
          description: |
            Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.
          content: *ref_5
    put:
      operationId: put_link
      summary: Edit Link
      description: |
        Edits an existing link. The link name and type cannot be modified.
      tags:
        - Single Links
      parameters:
        - name: name
          schema: *ref_6
          in: path
          required: true
          description: The name of the link.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - title: Edit Couchbase Link Request
                  allOf: &ref_22
                    - type: object
                      properties: &ref_13
                        type:
                          title: Edit Request Type
                          type: string
                          description: |
                            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: *ref_10
                    - title: Couchbase Specific Request
                      type: object
                      required: *ref_11
                      properties: *ref_12
                - title: Edit S3 Link Request
                  allOf: &ref_23
                    - type: object
                      properties: *ref_13
                    - title: S3 Specific Request
                      type: object
                      required: *ref_14
                      properties: *ref_15
                - title: Edit Azure Blob Link Request
                  allOf: &ref_24
                    - type: object
                      properties: *ref_13
                    - title: Azure Blob Specific Request
                      type: object
                      required: *ref_16
                      properties: *ref_17
      security:
        - AnalyticsManage: []
        - AlterLink: []
      responses:
        '200':
          description: The operation was successful.
        '400':
          description: |
            Bad request. A parameter has an incorrect value.
          content: *ref_4
        '500':
          description: |
            Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.
          content: *ref_5
    delete:
      operationId: delete_link
      summary: Delete Link
      description: |
        Deletes a link. The link cannot be deleted if any other entities are using it, such as a collection. The entities using the link need to be disconnected from the link, otherwise, the delete operation fails.
      tags:
        - Single Links
      parameters:
        - name: name
          schema: *ref_6
          in: path
          required: true
          description: The name of the link.
      security:
        - AnalyticsManage: []
        - DropLink: []
      responses:
        '200':
          description: The operation was successful.
        '400':
          description: |
            Bad request. A parameter has an incorrect value.
          content: *ref_4
        '500':
          description: |
            Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.
          content: *ref_5
components:
  parameters:
    CommonLink:
      name: name
      schema: *ref_6
      in: path
      required: true
      description: The name of the link.
    CommonTypeQuery:
      name: type
      schema:
        type: string
        enum:
          - couchbase
          - s3
          - azureblob
      in: query
      required: false
      description: |
        The type of the link. If this parameter is omitted, all link types are retrieved, excluding the `Local` link.
  schemas:
    CommonName:
      type: string
      description: The name of the link.
    CommonType:
      title: Create Request Type
      type: string
      description: |-
        The type of the link.

        * `couchbase`: A link to a remote Couchbase cluster.
        * `s3`: A link to the Amazon S3 service.
        * `azureblob`: A link to the Azure Blob Storage service.
      enum: *ref_18
    CommonTypeEdit:
      title: Edit Request Type
      type: string
      description: |
        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: *ref_10
    CommonClientCertificate:
      type: string
      description: |-
        For Couchbase links, this is 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.
    CommonEndpoint:
      type: string
      description: |-
        The endpoint URI.

        Required for Azure Blob links; optional for S3 links (e.g. when using S3-compatible storage).
    RequestCreateAll:
      type: object
      required: *ref_2
      properties: *ref_3
    RequestCreateCouchbase:
      title: Create Couchbase Link Request
      allOf: *ref_19
    RequestCreateS3:
      title: Create S3 Link Request
      allOf: *ref_20
    RequestCreateAzureBlob:
      title: Create Azure Blob Link Request
      allOf: *ref_21
    RequestEditAll:
      type: object
      properties: *ref_13
    RequestEditCouchbase:
      title: Edit Couchbase Link Request
      allOf: *ref_22
    RequestEditS3:
      title: Edit S3 Link Request
      allOf: *ref_23
    RequestEditAzureBlob:
      title: Edit Azure Blob Link Request
      allOf: *ref_24
    RequestSpecificCouchbase:
      title: Couchbase Specific Request
      type: object
      required: *ref_11
      properties: *ref_12
    RequestSpecificS3:
      title: S3 Specific Request
      type: object
      required: *ref_14
      properties: *ref_15
    RequestSpecificAzureBlob:
      title: Azure Blob Specific Request
      type: object
      required: *ref_16
      properties: *ref_17
    ResponseAll:
      title: Links
      description: These properties are common to all links.
      type: object
      discriminator: *ref_7
      required: *ref_8
      properties: *ref_9
    ResponseCouchbase:
      title: Couchbase Response
      description: These properties are returned for remote Couchbase links.
      allOf:
        - title: Links
          description: These properties are common to all links.
          type: object
          discriminator: *ref_7
          required: *ref_8
          properties: *ref_9
        - title: Couchbase Specific Response
          type: object
          required: &ref_25
            - activeHostname
            - bootstrapAlternateAddress
            - bootstrapHostname
            - certificate
            - clientCertificate
            - clientKey
            - clusterCompatibility
            - encryption
            - nodes
            - password
            - username
            - uuid
          properties: &ref_26
            activeHostname:
              type: string
              description: The remote hostname.
              x-has-example: true
              example: remoteHostName:8091
            bootstrapAlternateAddress:
              type: boolean
              description: Specifies whether the provided (bootstrap) hostname is an alternative address.
              x-has-example: true
              example: false
            bootstrapHostname:
              type: string
              description: The provided (bootstrap) hostname.
              x-has-example: true
              example: remoteHostName:8091
            certificate:
              type: string
              nullable: true
              description: |
                The content of the target cluster root certificate. Only set for links with full encryption. If not set, this property returns `null`.
              x-has-example: false
              example: null
            clientCertificate:
              type: string
              nullable: true
              description: |
                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`.
              x-has-example: false
              example: null
            clientKey:
              type: string
              nullable: true
              description: |
                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`.
              x-has-example: false
              example: null
            clusterCompatibility:
              type: integer
              description: For internal use only.
              x-has-example: true
              example: 393221
            encryption:
              type: string
              x-desc-name: encryption
              description: |
                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:
              type: array
              description: An array of objects, each of which contains information about a node in the target cluster.
              items:
                type: object
                title: Nodes
                properties: &ref_27
                  alternateAddresses:
                    type: string
                    description: |
                      The alternate address defined on the node, if any. If not defined, this property returns `null`.
                    x-has-example: false
                    example: null
                  hostname:
                    type: string
                    description: |
                      The hostname of the node. If not defined, this property returns `null`.
                    x-has-example: false
                    example: null
                  services:
                    type: object
                    title: Services
                    description: An object giving information about the services and ports configured on this node.
                    properties: &ref_28
                      cbas:
                        type: integer
                        description: The port number for a connection to the Analytics service.
                        x-has-example: true
                        example: 8095
                      cbasSSL:
                        type: integer
                        description: The port number for an encrypted connection to the Analytics service.
                        x-has-example: true
                        example: 18095
                      kv:
                        type: integer
                        description: The port number for a connection to the Data service.
                        x-has-example: true
                        example: 11210
                      kvSSL:
                        type: integer
                        description: The port number for an encrypted connection to the Data service.
                        x-has-example: true
                        example: 11207
                      mgmt:
                        type: integer
                        description: The port number for a connection to the Cluster Manager service.
                        x-has-example: true
                        example: 8091
                      mgmtSSL:
                        type: integer
                        description: The port number for an encrypted connection to the Cluster Manager service.
                        x-has-example: true
                        example: 18091
            password:
              type: string
              nullable: true
              description: |
                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`.
              x-has-example: true
              example: <redacted sensitive entry>
            username:
              type: string
              nullable: true
              description: |
                The remote username. Not set for links with full encryption using client certificate and client key. If not set, this property returns `null`.
              x-has-example: true
              example: remote.user
            uuid:
              type: string
              format: UUID
              description: A UUID uniquely identifying the link.
              x-has-example: true
              example: 6331e2a390125b662f7bcfd63ecb3a73
    ResponseCouchbaseSpecific:
      title: Couchbase Specific Response
      type: object
      required: *ref_25
      properties: *ref_26
    ResponseCouchbaseSpecificNode:
      type: object
      title: Nodes
      properties: *ref_27
    ResponseCouchbaseSpecificNodeServices:
      type: object
      title: Services
      description: An object giving information about the services and ports configured on this node.
      properties: *ref_28
    ResponseS3:
      title: S3 Response
      description: These properties are returned for S3 links.
      allOf:
        - title: Links
          description: These properties are common to all links.
          type: object
          discriminator: *ref_7
          required: *ref_8
          properties: *ref_9
        - title: S3 Specific Response
          type: object
          required: &ref_29
            - accessKeyId
            - crossRegion
            - instanceProfile
            - region
            - secretAccessKey
            - serviceEndpoint
            - sessionToken
          properties: &ref_30
            accessKeyId:
              type: string
              nullable: true
              description: |
                The Amazon S3 access key ID. If not set, this property returns `null`.
              x-has-example: true
              example: myAccessKey
            crossRegion:
              type: boolean
              description: |
                Whether the link can access S3 buckets in regions other than the configured region.
              x-has-example: true
              example: false
            externalId:
              type: string
              nullable: true
              description: |
                The external ID for cross-account role assumption. Only set when `roleArn` is used. If not set, this property returns `null`.
              x-has-example: false
              example: null
            instanceProfile:
              type: string
              nullable: true
              description: |
                Whether the EC2 instance profile is used for authentication. If not set, this property returns `null`.
              x-has-example: false
              example: null
            region:
              type: string
              description: The Amazon S3 region.
              x-has-example: true
              example: us-east-1
            roleArn:
              type: string
              nullable: true
              description: |
                The Amazon Resource Name (ARN) of the role assumed for cross-account authentication. If not set, this property returns `null`.
              x-has-example: false
              example: null
            secretAccessKey:
              type: string
              nullable: true
              description: |
                The Amazon S3 secret access key. This is redacted for the sake of security. If not set, this property returns `null`.
              x-has-example: true
              example: <redacted sensitive entry>
            serviceEndpoint:
              type: string
              nullable: true
              description: |
                The Amazon S3 service endpoint. If not set, this property returns `null`.
              x-has-example: true
              example: my.endpoint.uri
            sessionToken:
              type: string
              nullable: true
              description: |
                The Amazon S3 session token. Indicates that the link has temporary access, and that the `accessKeyId` and `secretAccessKey` are temporary credentials. This is redacted for the sake of security. If not set, this property returns `null`.
              x-has-example: true
              example: <redacted sensitive entry>
    ResponseS3Specific:
      title: S3 Specific Response
      type: object
      required: *ref_29
      properties: *ref_30
    ResponseAzureBlob:
      title: Azure Blob Response
      description: These properties are returned for Azure Blob links.
      allOf:
        - title: Links
          description: These properties are common to all links.
          type: object
          discriminator: *ref_7
          required: *ref_8
          properties: *ref_9
        - title: Azure Blob Specific Response
          type: object
          required: &ref_31
            - accountKey
            - accountName
            - endpoint
            - sharedAccessSignature
          properties: &ref_32
            accountKey:
              type: string
              nullable: true
              description: |
                The account key. Used for shared key authentication. This is redacted for the sake of security. If not set, this property returns `null`.
              x-has-example: true
              example: <redacted sensitive entry>
            accountName:
              type: string
              nullable: true
              description: |
                The account name. Used for shared key authentication. If not set, this property returns `null`.
              x-has-example: true
              example: myAccountName
            disableSslVerify:
              type: boolean
              description: |
                Whether SSL verification is disabled.
              x-has-example: true
              example: false
            endpoint:
              type: string
              nullable: true
              description: |
                The endpoint URI. If not set, this property returns `null`.
              x-has-example: true
              example: my.endpoint.uri
            sharedAccessSignature:
              type: string
              nullable: true
              description: |
                A token that can be used for authentication. Used for shared access signature authentication. This is redacted for the sake of security. If not set, this property returns `null`.
              x-has-example: true
              example: <redacted sensitive entry>
    ResponseAzureBlobSpecific:
      title: Azure Blob Specific Response
      type: object
      required: *ref_31
      properties: *ref_32
    Wrong:
      title: Errors
      type: object
      required: *ref_0
      properties: *ref_1
  responses:
    OK:
      description: The operation was successful.
    BadRequest:
      description: |
        Bad request. A parameter has an incorrect value.
      content: *ref_4
    InternalServerError:
      description: |
        Internal Server Error. Incorrect path or port number, incorrect credentials, badly formatted parameters, or missing arguments.
      content: *ref_5
  securitySchemes:
    AnalyticsManage:
      type: http
      scheme: basic
      description: |
        Users must have one of the following RBAC roles:

        * Full Admin
        * Cluster Admin
        * Enterprise Analytics Admin
    DescribeLink:
      type: http
      scheme: basic
      description: |
        Users must be granted the `Describe Link` privilege.
    CreateLink:
      type: http
      scheme: basic
      description: |
        Users must be granted the `Create Link` privilege.
    AlterLink:
      type: http
      scheme: basic
      description: |
        Users must be granted the `Alter Link` privilege.
    DropLink:
      type: http
      scheme: basic
      description: |
        Users must be granted the `Drop Link` privilege.
