openapi: 3.0.3
info:
  title: Delta Sharing API
  description: An Open Protocol for Secure Data Sharing
  license:
    name: AGPL v3.0
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  version: 0.0.0
tags:
  - name: CatalogService
  - name: DeltaSharingService
    description: Service exposing the official APIs for Delta Sharing.
  - name: official
    description: APIs which are part of published official document
  - name: proposed
    description: APIs which are part proposed and may or may not be part of official
  - name: schemas
    description: Schema discovery APIs
  - name: shares
    description: Share discovery APIs
  - name: tables
    description: Table query and inspection APIs
paths:
  /shares:
    get:
      tags:
        - DeltaSharingService
        - shares
        - official
      description: List shares accessible to a recipient.
      operationId: ListShares
      parameters:
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSharesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    post:
      tags:
        - CatalogService
        - shares
        - unofficial
      description: Create a new Share in the Delta Sharing service.
      operationId: CreateShare
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Share'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{name}:
    delete:
      tags:
        - CatalogService
        - shares
        - unofficial
      description: Delete a Share in the Delta Sharing service.
      operationId: DeleteShare
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}:
    get:
      tags:
        - DeltaSharingService
        - shares
        - official
      description: Get the metadata for a specific share.
      operationId: GetShare
      parameters:
        - name: share
          in: path
          description: The share id.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Share'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/all-tables:
    get:
      tags:
        - DeltaSharingService
        - shares
        - official
      description: List all the tables under all schemas in a share.
      operationId: ListShareTables
      parameters:
        - name: share
          in: path
          description: The share id.
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListShareTablesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas:
    get:
      tags:
        - DeltaSharingService
        - shares
        - official
      description: List the schemas in a share.
      operationId: ListSchemas
      parameters:
        - name: share
          in: path
          description: The share id.
          required: true
          schema:
            type: string
        - name: share
          in: query
          description: The share name to query. It's case-insensitive.
          schema:
            type: string
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchemasResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    post:
      tags:
        - CatalogService
        - schemas
        - unofficial
      description: Create a new Schema in the Delta Sharing service.
      operationId: CreateSchema
      parameters:
        - name: share
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schema'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{name}:
    delete:
      tags:
        - CatalogService
        - schemas
        - unofficial
      description: Delete a Schema in the Delta Sharing service.
      operationId: DeleteSchema
      parameters:
        - name: share
          in: path
          required: true
          schema:
            type: string
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{name}/tables:
    get:
      tags:
        - DeltaSharingService
        - shares
        - official
      description: List the tables in a given share's schema.
      operationId: ListSchemaTables
      parameters:
        - name: share
          in: path
          description: The share name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: The schema name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: maxResults
          in: query
          description: The maximum number of results per page that should be returned.
          schema:
            type: integer
            format: int32
        - name: pageToken
          in: query
          description: |-
            Specifies a page token to use. Set pageToken to the nextPageToken returned
             by a previous list request to get the next page of results.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSchemaTablesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{schema}/tables/{name}/metadata:
    get:
      tags:
        - DeltaSharingService
        - tables
        - official
      operationId: GetTableMetadata
      parameters:
        - name: share
          in: path
          description: The share name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: schema
          in: path
          description: The schema name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: The table name to query. It's case-insensitive.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /shares/{share}/schemas/{schema}/tables/{name}/version:
    get:
      tags:
        - DeltaSharingService
        - tables
        - official
      description: Get the current version for a table within a schema.
      operationId: GetTableVersion
      parameters:
        - name: share
          in: path
          description: The share name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: schema
          in: path
          description: The schema name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: name
          in: path
          description: The table name to query. It's case-insensitive.
          required: true
          schema:
            type: string
        - name: startingTimestamp
          in: query
          description: |-
            The startingTimestamp of the query, a string in the  ISO8601 format, in the UTC timezone,
             such as 2022-01-01T00:00:00Z. the server needs to return the earliest table version at
             or after the provided timestamp, can be earlier than the timestamp of table version 0.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTableVersionResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    DeltaLogMessage:
      type: object
      properties:
        protocol:
          $ref: '#/components/schemas/ProtocolDelta'
        metadata:
          $ref: '#/components/schemas/MetadatDelta'
    DeltaResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/DeltaLogMessage'
    Format:
      type: object
      properties:
        provider:
          type: string
          description: Name of the encoding for files in this table
        options:
          type: object
          additionalProperties:
            type: string
          description: A map containing configuration options for the format
    GetTableVersionResponse:
      type: object
      properties:
        version:
          type: string
          description: The table version that was requested.
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
    ListSchemaTablesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Table'
          description: The tables that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of tables.
             An empty or missing token means that no more tables are available for retrieval.
    ListSchemasResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Schema'
          description: The schemas that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of schemas.
             An empty or missing token means that no more schemas are available for retrieval.
    ListShareTablesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Table'
          description: The tables that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of tables.
             An empty or missing token means that no more tables are available for retrieval.
    ListSharesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Share'
          description: The shares that were requested.
        nextPageToken:
          type: string
          description: |-
            Token that can be used to retrieve the next page of shares.
             An empty or missing token means that no more shares are available for retrieval.
    MetadatDelta:
      type: object
      properties:
        deltaMetadata:
          allOf:
            - $ref: '#/components/schemas/Metadata'
          description: Metadata from Delta protocol
        version:
          type: string
          description: |-
            The table version the metadata corresponds to, returned when querying
             table data with a version or timestamp parameter, or cdf query
             with includeHistoricalMetadata set to true.
        size:
          type: string
          description: The size of the table in bytes, will be returned if available in the delta log.
        numFiles:
          type: string
          description: The number of files in the table, will be returned if available in the delta log.
    Metadata:
      type: object
      properties:
        id:
          type: string
          description: |-
            Unique identifier for this table
             Validate GUID
        name:
          type: string
          description: User-provided identifier for this table
        description:
          type: string
          description: User-provided description for this table
        format:
          allOf:
            - $ref: '#/components/schemas/Format'
          description: Specification of the encoding for the files stored in the table
        schemaString:
          type: string
          description: Schema of the table
        partitionColumns:
          type: array
          items:
            type: string
          description: An array containing the names of columns by which the data should be partitioned
        createdTime:
          type: string
          description: The time when this metadata action is created, in milliseconds since the Unix epoch
        options:
          type: object
          additionalProperties:
            type: string
          description: A map containing configuration options for the metadata action
    MetadataParquet:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for this table
        name:
          type: string
          description: User-provided identifier for this table
        description:
          type: string
          description: User-provided description for this table
        format:
          allOf:
            - $ref: '#/components/schemas/Format'
          description: Specification of the encoding for the files stored in the table
        schemaString:
          type: string
          description: Schema of the table
        partitionColumns:
          type: array
          items:
            type: string
          description: An array containing the names of columns by which the data should be partitioned
    ParquetLogMessage:
      type: object
      properties:
        protocol:
          $ref: '#/components/schemas/ProtocolParquet'
        metadata:
          $ref: '#/components/schemas/MetadataParquet'
    ParquetResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/ParquetLogMessage'
    ProtocolDelta:
      type: object
      properties:
        minReaderVersion:
          type: integer
          description: |-
            The minimum version of the protocol that a client must implement
             in order to correctly read a Delta Lake table.
          format: int32
        minWriterVersion:
          type: integer
          format: int32
    ProtocolParquet:
      type: object
      properties:
        minReaderVersion:
          type: integer
          description: |-
            The minimum version of the protocol that a client must implement
             in order to correctly read a Delta Lake table.
          format: int32
    QueryResponse:
      type: object
      properties:
        parquet:
          allOf:
            - $ref: '#/components/schemas/ParquetResponse'
          description: Parquet response format
        delta:
          allOf:
            - $ref: '#/components/schemas/DeltaResponse'
          description: Delta response format
    Schema:
      type: object
      properties:
        name:
          type: string
          description: The name of the schama
        share:
          type: string
          description: The share name that the schema belongs to.
      description: A schema is a logical grouping of tables. A schema may contain multiple tables.
    Share:
      type: object
      properties:
        name:
          type: string
          description: Name of the share.
        id:
          readOnly: true
          type: string
          description: Unique identifier for the share.
      description: |-
        A share is a logical grouping to share with recipients. A share can be shared with one or multiple recipients.
         A recipient can access all resources in a share. A share may contain multiple schemas.
    Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    Table:
      type: object
      properties:
        name:
          type: string
          description: The name of the table.
        schema:
          type: string
          description: The schema name that the table belongs to.
        share:
          type: string
          description: The share name that the table belongs to.
        id:
          readOnly: true
          type: string
          description: Unique identifier for the table.
        shareId:
          readOnly: true
          type: string
          description: A unique identifier for the share this table belongs to.
      description: A table is a Delta Lake table or a view on top of a Delta Lake table.