openapi: "3.0.2"
info:
  title: Page Server API
  version: "1.0"
servers:
  - url: ""
paths:
  /v1/status:
    description: Healthcheck endpoint
    get:
      description: Healthcheck
      security: []
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: integer
  /v1/tenant/{tenant_id}/timeline:
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: hex
      - name: include-non-incremental-logical-size
        in: query
        schema:
          type: string
          description: Controls calculation of current_logical_size_non_incremental
    get:
      description: Get timelines for tenant
      responses:
        "200":
          description: TimelineInfo
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TimelineInfo"
        "400":
          description: Error when no tenant id found in path
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "403":
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "500":
          description: Generic operation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/tenant/{tenant_id}/timeline/{timeline_id}:
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: hex
      - name: timeline_id
        in: path
        required: true
        schema:
          type: string
          format: hex
      - name: include-non-incremental-logical-size
        in: query
        schema:
          type: string
          description: Controls calculation of current_logical_size_non_incremental
    get:
      description: Get info about the timeline
      responses:
        "200":
          description: TimelineInfo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimelineInfo"
        "400":
          description: Error when no tenant id found in path or no timeline id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "403":
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "500":
          description: Generic operation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


  /v1/tenant/{tenant_id}/timeline/{timeline_id}/attach:
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: hex
      - name: timeline_id
        in: path
        required: true
        schema:
          type: string
          format: hex
    post:
      description: Attach remote timeline
      responses:
        "200":
          description: Timeline attaching scheduled
        "400":
          description: Error when no tenant id found in path or no timeline id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "403":
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "404":
          description: Timeline not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundError"
        "409":
          description: Timeline download is already in progress
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictError"
        "500":
          description: Generic operation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


  /v1/tenant/{tenant_id}/timeline/{timeline_id}/detach:
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: hex
      - name: timeline_id
        in: path
        required: true
        schema:
          type: string
          format: hex
    post:
      description: Detach local timeline
      responses:
        "200":
          description: Timeline detached
        "400":
          description: Error when no tenant id found in path or no timeline id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "403":
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "500":
          description: Generic operation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"


  /v1/tenant/{tenant_id}/timeline/:
    parameters:
      - name: tenant_id
        in: path
        required: true
        schema:
          type: string
          format: hex
    post:
      description: |
        Create a timeline. Returns new timeline id on success.\
        If no new timeline id is specified in parameters, it would be generated. It's an error to recreate the same timeline.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                new_timeline_id:
                  type: string
                  format: hex
                ancestor_timeline_id:
                  type: string
                  format: hex
                ancestor_start_lsn:
                  type: string
                  format: hex
      responses:
        "201":
          description: TimelineInfo
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimelineInfo"
        "400":
          description: Malformed timeline create request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "403":
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "409":
          description: Timeline already exists, creation skipped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictError"
        "500":
          description: Generic operation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v1/tenant/:
    get:
      description: Get tenants list
      responses:
        "200":
          description: TenantInfo
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TenantInfo"
        "401":
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "403":
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "500":
          description: Generic operation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      description: |
        Create a tenant. Returns new tenant id on success.\
        If no new tenant id is specified in parameters, it would be generated. It's an error to recreate the same tenant.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                new_tenant_id:
                  type: string
                  format: hex
      responses:
        "201":
          description: New tenant created successfully
          content:
            application/json:
              schema:
                type: string
                format: hex
        "400":
          description: Malformed tenant create request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "403":
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForbiddenError"
        "409":
          description: Tenant already exists, creation skipped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConflictError"
        "500":
          description: Generic operation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    TenantInfo:
      type: object
      required:
        - id
        - state
      properties:
        id:
          type: string
        state:
          type: string
    TimelineInfo:
      type: object
      required:
        - timeline_id
        - tenant_id
      properties:
        timeline_id:
          type: string
          format: hex
        tenant_id:
          type: string
          format: hex
        local:
          $ref: "#/components/schemas/LocalTimelineInfo"
        remote:
          $ref: "#/components/schemas/RemoteTimelineInfo"
    RemoteTimelineInfo:
      type: object
      required:
        - awaits_download
      properties:
        awaits_download:
          type: boolean
        remote_consistent_lsn:
          type: string
          format: hex
    LocalTimelineInfo:
      type: object
      required:
        - last_record_lsn
        - disk_consistent_lsn
        - timeline_state
      properties:
        last_record_lsn:
          type: string
          format: hex
        disk_consistent_lsn:
          type: string
          format: hex
        timeline_state:
          type: string
        ancestor_timeline_id:
          type: string
          format: hex
        ancestor_lsn:
          type: string
          format: hex
        prev_record_lsn:
          type: string
          format: hex
        current_logical_size:
          type: integer
        current_logical_size_non_incremental:
          type: integer

    Error:
      type: object
      required:
        - msg
      properties:
        msg:
          type: string
    UnauthorizedError:
      type: object
      required:
        - msg
      properties:
        msg:
          type: string
    ForbiddenError:
      type: object
      required:
        - msg
      properties:
        msg:
          type: string
    NotFoundError:
      type: object
      required:
        - msg
      properties:
        msg:
          type: string
    ConflictError:
      type: object
      required:
        - msg
      properties:
        msg:
          type: string

security:
  - JWT: []
