lakeFS staging API

openapi: 3.0.0
info:
  description: lakeFS HTTP API
  title: lakeFS actions staging API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: /api/v1
  description: lakeFS server endpoint
security:
- jwt_token: []
- basic_auth: []
- cookie_auth: []
- oidc_auth: []
- saml_auth: []
tags:
- name: staging
paths:
  /repositories/{repository}/branches/{branch}/staging/backing:
    parameters:
    - in: path
      name: repository
      required: true
      schema:
        type: string
    - in: path
      name: branch
      required: true
      schema:
        type: string
    - in: query
      name: path
      description: relative to the branch
      required: true
      schema:
        type: string
    get:
      tags:
      - staging
      operationId: getPhysicalAddress
      summary: generate an address to which the client can upload an object
      parameters:
      - in: query
        name: presign
        required: false
        schema:
          type: boolean
      responses:
        200:
          description: physical address for staging area
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StagingLocation'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
        429:
          description: too many requests
        default:
          $ref: '#/components/responses/ServerError'
    put:
      tags:
      - staging
      operationId: linkPhysicalAddress
      summary: associate staging on this physical address with a path
      description: 'Link the physical address with the path in lakeFS, creating an uncommitted change.

        The given address can be one generated by getPhysicalAddress, or an address outside the repository''s storage namespace.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StagingMetadata'
      parameters:
      - $ref: '#/components/parameters/IfNoneMatch'
      - $ref: '#/components/parameters/IfMatch'
      responses:
        200:
          description: object metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectStats'
        400:
          $ref: '#/components/responses/ValidationError'
        401:
          $ref: '#/components/responses/Unauthorized'
        403:
          $ref: '#/components/responses/Forbidden'
        404:
          $ref: '#/components/responses/ServerError'
        409:
          description: conflict with a commit, try here
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StagingLocation'
        412:
          $ref: '#/components/responses/PreconditionFailed'
        429:
          description: too many requests
        501:
          $ref: '#/components/responses/NotImplemented'
        default:
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotImplemented:
      description: Not Implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PreconditionFailed:
      description: Precondition Failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    StagingLocation:
      type: object
      description: location for placing an object when staging it
      properties:
        physical_address:
          type: string
        presigned_url:
          type: string
          nullable: true
          description: if presign=true is passed in the request, this field will contain a pre-signed URL to use when uploading
        presigned_url_expiry:
          type: integer
          format: int64
          description: 'If present and nonzero, physical_address is a pre-signed URL and

            will expire at this Unix Epoch time.  This will be shorter than

            the pre-signed URL lifetime if an authentication token is about

            to expire.


            This field is *optional*.

            '
    ObjectUserMetadata:
      type: object
      additionalProperties:
        type: string
    ObjectStats:
      type: object
      required:
      - checksum
      - physical_address
      - path
      - path_type
      - mtime
      properties:
        path:
          type: string
        path_type:
          type: string
          enum:
          - common_prefix
          - object
        physical_address:
          type: string
          description: 'The location of the object on the underlying object store.

            Formatted as a native URI with the object store type as scheme ("s3://...", "gs://...", etc.)

            Or, in the case of presign=true, will be an HTTP URL to be consumed via regular HTTP GET

            '
        physical_address_expiry:
          type: integer
          format: int64
          description: 'If present and nonzero, physical_address is a pre-signed URL and

            will expire at this Unix Epoch time.  This will be shorter than

            the pre-signed URL lifetime if an authentication token is about

            to expire.


            This field is *optional*.

            '
        checksum:
          type: string
        size_bytes:
          type: integer
          format: int64
          description: 'The number of bytes in the object.  lakeFS always populates this

            field when returning ObjectStats.  This field is optional _for

            the client_ to supply, for instance on upload.

            '
        mtime:
          type: integer
          format: int64
          description: Unix Epoch in seconds
        metadata:
          $ref: '#/components/schemas/ObjectUserMetadata'
        content_type:
          type: string
          description: Object media type
    StagingMetadata:
      type: object
      description: information about uploaded object
      properties:
        staging:
          $ref: '#/components/schemas/StagingLocation'
        checksum:
          type: string
          description: unique identifier of object content on backing store (typically ETag)
        size_bytes:
          type: integer
          format: int64
        user_metadata:
          type: object
          additionalProperties:
            type: string
        content_type:
          type: string
          description: Object media type
        mtime:
          type: integer
          format: int64
          description: Unix Epoch in seconds.  May be ignored by server.
        force:
          type: boolean
          default: false
      required:
      - staging
      - checksum
      - size_bytes
    Error:
      type: object
      required:
      - message
      properties:
        message:
          description: short message explaining the error
          type: string
  parameters:
    IfMatch:
      in: header
      name: If-Match
      description: Set to the object's ETag to atomically allow operations only if the object's current ETag matches the provided value.
      example: 2e9ec317e197e02e4264d128c2e7e681
      required: false
      schema:
        type: string
    IfNoneMatch:
      in: header
      name: If-None-Match
      description: Set to "*" to atomically allow the upload only if the key has no object yet. Other values are not supported.
      example: '*'
      required: false
      schema:
        type: string
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
    jwt_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
    cookie_auth:
      type: apiKey
      in: cookie
      name: internal_auth_session
    oidc_auth:
      type: apiKey
      in: cookie
      name: oidc_auth_session
    saml_auth:
      type: apiKey
      in: cookie
      name: saml_auth_session