openapi: "3.0.3"
info:
  version: 1.0.0-beta
  x-audience: partner
  title: Collibra Protect API - Partner
  description:
    API to retrieve the data access rule set it needs to synchronize.
    This API is targeted to be used by Collibra Partners.
servers:
  - url: /rest/protect/v1
tags:
  - name: Synchronizations
    description: Retrieval of detailed information on synchronizations.
paths:
  /synchronizations/byDataSource:
    get:
      tags:
        - Synchronizations
      summary: Returns the details of the synchronization for the provided data source.
      operationId: getSynchronizationByDataSource
      parameters:
        - in: query
          description: Name of the data source
          name: dataSource
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The set of data access rules to synchronize
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Synchronization'
        "400":
          $ref: "#/components/responses/InvalidRequest400"
        "401":
          $ref: "#/components/responses/InvalidRequest401"
        '403':
          $ref: "#/components/responses/InvalidRequest403"
        '404':
          $ref: "#/components/responses/InvalidRequest404"
        "500":
          $ref: "#/components/responses/InvalidRequest500"
      security:
        - basicAuth: [ ]
components:
  schemas:
    Synchronization:
      description: All information needed to perform synchronization
      type: object
      properties:
        id:
          description: Operation id
          type: string
          example: "37c8d656-cb03-4085-a3c0-2de40ec0f3f1"
        dataAccessRuleSet:
          $ref: '#/components/schemas/DataAccessRuleSet'
    Provider:
      type: string
      description: Value must be "Snowflake", "GoogleBigQuery, or "AWSLakeFormation"
      example: "AWSLakeFormation"
    Access:
      type: string
      description: 'Possible values are: `Read` or `NoChange`.'
      example: "Read"
    ProviderDetails:
      description: The provider specific details. For example, AWSLakeFormation contains the property awsRegion, which denotes in which region the database is located.
      type: object
      additionalProperties:
        type: string
      example:
        awsRegion: us-east-1
    DataAccessRuleSet:
      description: All of the data access rules that need to be synchronized.
      type: object
      properties:
        databases:
          type: array
          items:
            $ref: '#/components/schemas/Database'
      required:
        - databases
    Database:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/Provider'
        providerDetails:
          $ref: '#/components/schemas/ProviderDetails'
        id:
          type: string
          description: The id of the database
          example: "2e35030a-3632-479a-8f2e-72c131afb882"
        name:
          type: string
          description: The name of the database
          example: "database_name"
        schemas:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/DatabaseSchema'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseTag'
        customMaskings:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseCustomMasking'
      required:
        - provider
        - id
        - name
        - schema
        - tags
        - customMaskings
    DatabaseSchema:
      type: object
      properties:
        id:
          type: string
          description: The id of the database schema
          example: "76549f59-b341-4bb7-abdd-9cdf98a50b1c"
        name:
          type: string
          description: The name of the database schema
          example: "schema_name"
        tables:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseTable'
      required:
        - id
        - name
        - tables
    DatabaseTable:
      type: object
      properties:
        id:
          type: string
          description: The id of the database table
          example: "d0dd3533-163d-4417-bcbb-4fb09e347128"
        name:
          type: string
          description: The name of the database table
          example: "table_name"
        columns:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseColumn'
        accesses:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseTableAccessRule'
      required:
        - id
        - name
        - columns
        - accesses
    DatabaseColumn:
      type: object
      properties:
        id:
          type: string
          description: The id of the database column
          example: "03e597ce-645e-40b1-b1a0-9c322cf03533"
        name:
          type: string
          description: The name of the database column
          example: "column_name"
        dataType:
          description: |
            The data type as it is declared by the provider. For example: String, Integer, Varchar, Blob, Boolean, ...
          type: string
          example: "Boolean"
        precision:
          type: integer
          description: The precision of the column.
          example: 10
        scale:
          type: integer
          description: The scale of the column.
          example: 2
        tags:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseColumnTag'
        accesses:
          type: array
          items:
            $ref: '#/components/schemas/DatabaseColumnAccessRule'
      required:
        - id
        - name
        - tags
        - accesses
    DatabaseColumnTag:
      type: object
      properties:
        id:
          type: string
          description: The id of database column tag
          example: "5761adfa-9ca1-44b3-8a45-36d78f69d2b4"
        name:
          type: string
          description: The name of database column tag
          example: "PII"
      required:
        - id
        - name
    DatabaseTableAccessRule:
      type: object
      properties:
        group:
          type: string
          description: The name of protect group
          example: "Engineering"
        access:
          $ref: '#/components/schemas/Access'
      required:
        - group
        - access
    DatabaseColumnAccessRule:
      type: object
      properties:
        group:
          type: string
          description: The name of protect group
          example: "Engineering"
        access:
          $ref: '#/components/schemas/Access'
        masking:
          $ref: '#/components/schemas/Masking'
        rowFilter:
          $ref: '#/components/schemas/RowFilter'
      required:
        - group
        - access
    BaseMasking:
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/MaskingType'
    Masking:
      oneOf:
        - $ref: '#/components/schemas/NoMasking'
        - $ref: '#/components/schemas/DefaultMasking'
        - $ref: '#/components/schemas/ConstantMasking'
        - $ref: '#/components/schemas/HashMasking'
        - $ref: '#/components/schemas/ShowLastMasking'
        - $ref: '#/components/schemas/CustomMasking'
      discriminator:
        propertyName: type
        mapping:
          None: '#/components/schemas/NoMasking'
          Default: '#/components/schemas/DefaultMasking'
          Constant: '#/components/schemas/ConstantMasking'
          Hash: '#/components/schemas/HashMasking'
          ShowLast: '#/components/schemas/ShowLastMasking'
          Custom: '#/components/schemas/CustomMasking'
    MaskingType:
      type: string
      description: 'Possible values are: `None`, `Default`, `Constant`, `Hash` or `ShowLast`.'
      example: "Default"
    NoMasking:
      allOf:
        - $ref: '#/components/schemas/BaseMasking'
    ConstantMasking:
      description: 'This masked strategy is not supported by the Protect application therefore it is deprecated and it will be removed in new versions of the API. Use DefaultMasking instead.'
      allOf:
        - $ref: '#/components/schemas/BaseMasking'
        - type: object
          properties:
            constant:
              type: string
    DefaultMasking:
      description: 'The masked value applied is source dependent and chosen based on the column data type.'
      allOf:
        - $ref: '#/components/schemas/BaseMasking'
    HashMasking:
      allOf:
        - $ref: '#/components/schemas/BaseMasking'
    ShowLastMasking:
      allOf:
        - $ref: '#/components/schemas/BaseMasking'
        - type: object
          properties:
            numberOfCharacters:
              type: integer
              description: The number of characters to display
              example: 2
    CustomMasking:
      allOf:
        - $ref: '#/components/schemas/BaseMasking'
        - type: object
          properties:
            customMaskingId:
              type: string
              format: uuid
              description: The id of custom masking
              example: "33d4fbcd-5e10-4a47-a3d0-8df8a501fbgh"
            customMaskingName:
              type: string
              description: The name of custom masking
              example: "custom_masking_name"
    RowFilter:
      type: object
      properties:
        operator:
          $ref: '#/components/schemas/RowFilterOperator'
        values:
          type: array
          items:
            type: string
            description: The value of row filter
            example: "US"
          uniqueItems: true
    RowFilterOperator:
      type: string
      description: 'Possible values are: `Equals` or `NotEquals`.'
      example: "Equals"
    DatabaseTag:
      type: object
      properties:
        id:
          type: string
          description: The id of database tag
          example: "8761adfa-9ca1-44b3-8a45-36d78f69d2b4"
        name:
          type: string
          description: The name of database tag
          example: "tag_name"
        maskings:
          type: array
          items:
            $ref: '#/components/schemas/GroupMasking'
      required:
        - id
        - tag
        - maskings
    GroupMasking:
      type: object
      properties:
        group:
          type: string
          description: The name of protect group
          example: "Engineering"
        masking:
          $ref: '#/components/schemas/Masking'
      required:
        - group
        - masking
    DatabaseCustomMasking:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The id of database custom masking
          example: "4265adfa-9ca1-44b3-8a45-36d78f69d2b4"
        name:
          type: string
          description: The name of database custom masking
          example: "database_custom_masking"
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/MaskingMappings'
    MaskingMappings:
      description: a mapping of the data type and function name used to provide the custom mapping.
      properties:
        dataType:
          type: string
          description: The name of the data type (String, Number, Date ...). Data types name depend on the provider, a list of compatible types per provider is available in the documentation.
          example: "String"
        functionName:
          type: string
          description: The name of the function that will be used on the provider to provide the custom masking.
          example: "hash_my_string"
      required:
        - dataType
        - functionName
    StandardErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          description: HTTP response code
          example: 400
        titleMessage:
          type: string
          description: The title of the error message.
          example: "Invalid Request"
        helpMessage:
          type: string
          description: A message containing actions you can take regarding the error.
          example: "Please check the application logs for more information."
        userMessage:
          type: string
          description: A user friendly error message.
          example: "The request is not valid."
        errorCode:
          type: string
          description: An error code identifier.
          example: "invalidRequest"
  responses:
    InvalidRequest400:
      description: The request is not valid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 400
            titleMessage: "Invalid Request"
            helpMessage: "Please check the application logs for more information."
            userMessage: "The request is not valid."
            errorCode: "invalidRequest"
    InvalidRequest401:
      description: The client is not authenticated.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 401
            titleMessage: "Unauthorized"
            helpMessage: "Please check the application logs for more information."
            userMessage: "Failed to authenticate request through basic credentials"
            errorCode: "authenticationFailed"
    InvalidRequest403:
      description: The user lacks permissions.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 403
            titleMessage: "Forbidden"
            helpMessage: "Please check the application logs for more information."
            userMessage: "The user does not have the required permissions."
            errorCode: "authorizationFailed"
    InvalidRequest404:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 404
            titleMessage: "Not Found"
            helpMessage: "Please check the application logs for more information."
            userMessage: "The resource could not be found"
            errorCode: "notfound"
    InvalidRequest500:
      description: An unexpected error happened.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StandardErrorResponse"
          example:
            statusCode: 500
            titleMessage: "Internal Server Error"
            helpMessage: "Please check the application logs for more information."
            userMessage: "An unexpected error happened."
            errorCode: "unexpectedError"
  securitySchemes:
    basicAuth:
      description: The APIs require Basic HTTP authentication.
      type: http
      scheme: basic
