Unity Catalog External Locations API

openapi: 3.2.0
info:
  title: Unity Catalog External Locations API
  version: '0.1'
servers:
- url: http://localhost:8080/api/2.1/unity-catalog
  description: Localhost reference server
tags:
- name: External Locations
paths:
  /external-locations:
    post:
      tags:
      - External Locations
      summary: Create an external location
      description: Creates a new external location entry in the metastore. The caller must be a metastore admin to be able to create external locations.
      operationId: createExternalLocation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalLocation'
      responses:
        '200':
          description: The new external location was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalLocationInfo'
    get:
      tags:
      - External Locations
      summary: List external locations
      description: Gets an array of external locations (ExternalLocationInfo objects) from the metastore. The caller must be a metastore admin, the owner of the external location, or a user with some privilege on the external location.
      operationId: listExternalLocations
      parameters:
      - name: max_results
        in: query
        description: 'Maximum number of external locations to return. If not set, all external locations are returned.

          '
        schema:
          type: integer
          format: int32
          maximum: 1000
        required: false
      - name: page_token
        in: query
        description: Opaque pagination token to go to the next page.
        schema:
          type: string
        required: false
      responses:
        '200':
          description: The external location list was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListExternalLocationsResponse'
  /external-locations/{name}:
    parameters:
    - name: name
      in: path
      description: Name of the external location.
      required: true
      schema:
        type: string
    get:
      tags:
      - External Locations
      summary: Get an external location
      description: Gets an external location from the metastore. The caller must be a metastore admin, the owner of the external location, or a user with some privilege on the external location.
      operationId: getExternalLocation
      responses:
        '200':
          description: The external location was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalLocationInfo'
    delete:
      tags:
      - External Locations
      summary: Delete an external location
      description: Deletes the specified external location from the metastore. The caller must be a metastore admin or the owner of the external location.
      operationId: deleteExternalLocation
      parameters:
      - name: force
        in: query
        description: Force deletion even if there are dependent external tables or mounts.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: The external location was successfully deleted.
    patch:
      tags:
      - External Locations
      summary: Update an external location
      description: Updates an external location in the metastore. The caller must be the owner of the external location or a metastore admin.
      operationId: updateExternalLocation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateExternalLocation'
      responses:
        '200':
          description: The external location was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalLocationInfo'
components:
  schemas:
    UpdateExternalLocation:
      type: object
      properties:
        url:
          description: Path URL of the external location.
          type: string
        credential_name:
          description: Name of the storage credential used with this location.
          type: string
        comment:
          description: User-provided free-form text description.
          type: string
        owner:
          description: The owner of the external location.
          type: string
        new_name:
          description: New name for the external location.
          type: string
    ListExternalLocationsResponse:
      type: object
      properties:
        external_locations:
          description: An array of external locations.
          type: array
          items:
            $ref: '#/components/schemas/ExternalLocationInfo'
        next_page_token:
          type: string
          description: Opaque token to retrieve the next page of results. Absent if there are no more pages. __page_token__ should be set to this value for the next request (for the next page of results).
    CreateExternalLocation:
      type: object
      required:
      - name
      - url
      - credential_name
      properties:
        name:
          description: Name of the external location.
          type: string
        url:
          description: Path URL of the external location.
          type: string
        credential_name:
          description: Name of the storage credential used with this location.
          type: string
        comment:
          description: User-provided free-form text description.
          type: string
    ExternalLocationInfo:
      type: object
      properties:
        name:
          description: Name of the external location.
          type: string
        id:
          description: Unique identifier for the external location.
          type: string
        url:
          description: Path URL of the external location.
          type: string
        credential_name:
          description: Name of the storage credential used with this location.
          type: string
        comment:
          description: User-provided free-form text description.
          type: string
        owner:
          description: The owner of the external location.
          type: string
        credential_id:
          description: Unique ID of the location's storage credential.
          type: string
        created_at:
          description: Time at which this external location was created, in epoch milliseconds.
          type: integer
          format: int64
        created_by:
          description: Username of external location creator.
          type: string
        updated_at:
          description: Time at which external location this was last modified, in epoch milliseconds.
          type: integer
          format: int64
        updated_by:
          description: Username of user who last modified the external location.
          type: string