---
openapi: 3.0.3
info:
  title: rostore-service API
  version: 2.0.1
tags:
- name: Administration - Api-Keys
  description: Collection of operations to manage the api-keys
- name: Administration - Container
  description: Collection of operations to manage containers
- name: Administration - Media
  description: Collection of operations to manage the underlying media
- name: Operations - Key-Value Store
paths:
  /admin/api-key:
    post:
      tags:
      - Administration - Api-Keys
      summary: Creates a new Api-Key with a set of given permissions
      description: Operation requires a store-wide grant permission
      parameters:
      - name: eol
        in: header
        schema:
          format: int64
          type: integer
      - name: options
        in: header
        schema:
          type: string
      - name: ttl
        in: header
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyPermissions'
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Api-Key created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyDefinition'
      security:
      - apiKey: []
  /admin/api-key/list:
    get:
      tags:
      - Administration - Api-Keys
      summary: Returns a list of Api-Keys in the store
      description: Operation requires a store-wide list permission
      parameters:
      - name: start-api-key
        in: query
        schema:
          type: string
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: The api-key list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringKeyList'
      security:
      - apiKey: []
  /admin/api-key/repair-root:
    get:
      tags:
      - Administration - Api-Keys
      summary: Repairs a broken root Api-Key entry
      description: Operation requires a store-wide root permission
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Root is repaired successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyDefinition'
      security:
      - apiKey: []
  /admin/api-key/{request-api-key}:
    get:
      tags:
      - Administration - Api-Keys
      summary: Returns a set of permissions associated with an Api-Key
      description: Operation requires a store-wide read permission
      parameters:
      - name: request-api-key
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: header
        schema:
          format: int64
          type: integer
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "404":
          description: The API-Key not found or not access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: The api-key definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyDefinition'
      security:
      - apiKey: []
    put:
      tags:
      - Administration - Api-Keys
      summary: Updates an existing Api-Key with a set of given permissions
      description: Operation requires a store-wide grant permission
      parameters:
      - name: request-api-key
        in: path
        required: true
        schema:
          type: string
      - name: eol
        in: header
        schema:
          format: int64
          type: integer
      - name: options
        in: header
        schema:
          type: string
      - name: ttl
        in: header
        schema:
          format: int64
          type: integer
      - name: version
        in: header
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyPermissions'
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "409":
          description: Version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Api-Key has been updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyDefinition'
      security:
      - apiKey: []
  /admin/container/{container}:
    post:
      tags:
      - Administration - Container
      summary: Creates a new container in the store
      description: Operation requires a store-wide create permission
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContainerMeta'
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "409":
          description: Version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "507":
          description: Quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Container has been created successfully.
      security:
      - apiKey: []
    delete:
      tags:
      - Administration - Container
      summary: Delete an existing container in the store
      description: Operation requires a store-wide delete permission
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "409":
          description: Version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "507":
          description: Quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Container removed successfully.
      security:
      - apiKey: []
  /admin/container/{container}/meta:
    get:
      tags:
      - Administration - Container
      summary: Retrieves a meta-information for a given container
      description: Operation requires a store-wide read permission
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Meta data is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerMeta'
      security:
      - apiKey: []
  /admin/container/{container}/space:
    get:
      tags:
      - Administration - Container
      summary: Retrieves a space usage for a given container
      description: Operation requires a store-wide read permission
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Container space usage info is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockAllocationState'
      security:
      - apiKey: []
  /admin/store/create:
    post:
      tags:
      - Administration - Media
      summary: Initializes a new store
      description: This operation can only start a root user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoStoreProperties'
      responses:
        "200":
          description: OK
      security:
      - apiKey: []
  /admin/store/mapper-properties:
    get:
      tags:
      - Administration - Media
      summary: Provides information on store space usage
      description: Operation requires a store-wide read permission
      responses:
        "200":
          description: OK
      security:
      - apiKey: []
  /admin/store/ping:
    get:
      tags:
      - Administration - Media
      summary: Check for availability
      description: This operation can only start a root user
      responses:
        "200":
          description: OK
      security:
      - apiKey: []
  /admin/store/shutdown:
    get:
      tags:
      - Administration - Media
      summary: Shutdowns this store
      description: This operation can only start a root user
      responses:
        "200":
          description: OK
      security:
      - apiKey: []
  /admin/store/space:
    get:
      tags:
      - Administration - Media
      summary: Provides information on store space usage
      description: Operation requires a store-wide read permission
      responses:
        "200":
          description: OK
      security:
      - apiKey: []
  /admin/store/version:
    get:
      tags:
      - Administration - Media
      summary: Get version
      description: This operation is not protected
      responses:
        "200":
          description: OK
      security:
      - apiKey: []
  /container/list:
    get:
      tags:
      - Operations - Key-Value Store
      summary: Lists all the container the user has access to
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: List of containers
          content:
            application/json: {}
      security:
      - apiKey: []
  /container/{container}/key/{key}:
    get:
      tags:
      - Operations - Key-Value Store
      summary: Retrieves a value by the given key from the container
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "404":
          description: The key not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Value for the key
          content:
            application/octet-stream: {}
      security:
      - apiKey: []
    post:
      tags:
      - Operations - Key-Value Store
      summary: Posts a key-value pair to the container
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        schema:
          type: string
      - name: eol
        in: header
        schema:
          format: int64
          type: integer
      - name: options
        in: header
        schema:
          type: string
      - name: ttl
        in: header
        schema:
          format: int64
          type: integer
      - name: version
        in: header
        schema:
          format: int64
          type: integer
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "409":
          description: Version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "507":
          description: Quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Key-value has been stored successfully.
      security:
      - apiKey: []
    delete:
      tags:
      - Operations - Key-Value Store
      summary: Deletes permanently a key-value pair from the container
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      - name: key
        in: path
        required: true
        schema:
          type: string
      - name: options
        in: header
        schema:
          type: string
      - name: version
        in: header
        schema:
          format: int64
          type: integer
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "409":
          description: Version conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: Key-value has been deleted successfully.
      security:
      - apiKey: []
  /container/{container}/keys:
    get:
      tags:
      - Operations - Key-Value Store
      summary: Lists keys from the container
      description: "The keys are not processed in the alphabetic order. The order\
        \ depends on the number of shards. Internally, each shard is processed independently."
      parameters:
      - name: container
        in: path
        required: true
        schema:
          type: string
      - name: continuation-key
        in: query
        schema:
          type: string
      - name: start-with-key
        in: query
        schema:
          type: string
      responses:
        "403":
          description: No access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "500":
          description: Internal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRepresentation'
        "200":
          description: List of keys
          content:
            application/json: {}
      security:
      - apiKey: []
components:
  schemas:
    ApiKeyDefinition:
      description: Api Key
      type: object
      properties:
        key:
          description: The API KEY itself
          type: string
          example: 4e030824-08bf-4a0a-b6cb-bafa19406349
        lastUpdate:
          format: int64
          description: Unix Timestamp for the last update
          type: integer
        apiKeyPermissions:
          description: Set of permissions managed for this key
          type: object
          allOf:
          - $ref: '#/components/schemas/ApiKeyPermissions'
    ApiKeyPermissions:
      description: Permissions associated with APIKEY
      type: object
      properties:
        containerPermissions:
          description: Permissions granted per container
          type: object
          additionalProperties:
            uniqueItems: true
            type: array
            items:
              $ref: '#/components/schemas/Permission'
          example:
            yourStoreName:
            - READ
            - LIST
            - WRITE
            - DELETE
            - CREATE
            - GRANT
        storePermissions:
          description: Permissions granted on store
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          example:
          - READ
          - LIST
          - WRITE
          - DELETE
          - CREATE
          - GRANT
          - SUPER
    BlockAllocationState:
      type: object
      properties:
        payloadSize:
          format: int64
          type: integer
        totalLockedSize:
          format: int64
          type: integer
        lockedFreeSize:
          format: int64
          type: integer
    ContainerListProperties:
      type: object
      properties:
        autoCloseContainersAfterMillis:
          format: int64
          type: integer
        cleanupIntervalMillis:
          format: int64
          type: integer
        maxCleanupsPerCycle:
          format: int32
          type: integer
        maxContainersPerList:
          format: int32
          type: integer
        maxContainersListSize:
          format: int64
          type: integer
        maxKeyOperationsPerShard:
          format: int32
          type: integer
    ContainerMeta:
      type: object
      properties:
        creationTime:
          format: int64
          type: integer
        maxSize:
          format: int64
          type: integer
        shardNumber:
          format: int32
          type: integer
        maxTTL:
          format: int64
          type: integer
    ErrorRepresentation:
      type: object
      properties:
        message:
          type: string
        trackingId:
          type: string
    MediaPropertiesBuilder:
      type: object
      properties:
        maxTotalSize:
          format: int64
          type: integer
        blockSize:
          format: int32
          type: integer
        closeUnusedBlocksAfterMillis:
          format: int64
          type: integer
        closeUnusedSequencesAfterMillis:
          format: int64
          type: integer
    Permission:
      enum:
      - READ
      - LIST
      - WRITE
      - DELETE
      - CREATE
      - GRANT
      - SUPER
      type: string
    RoStoreProperties:
      type: object
      properties:
        mediaProperties:
          description: Media properties
          type: object
          allOf:
          - $ref: '#/components/schemas/MediaPropertiesBuilder'
          example:
            maxTotalSize: 1073741824
            blockSize: 4096
            closeUnusedBlocksAfterMillis: 5000
            closeUnusedSequencesAfterMillis: 10000
        containerListProperties:
          description: Container list properties
          type: object
          allOf:
          - $ref: '#/components/schemas/ContainerListProperties'
          example:
            autoCloseContainersAfterMillis: 60000
            cleanupIntervalMillis: 5000
            maxCleanupsPerCycle: 5
            maxContainersPerList: 1024
            maxContainersListSize: 5242880
            maxKeyOperationsPerShard: 10
    StringKeyList:
      type: object
      properties:
        keys:
          type: array
          items:
            type: string
        more:
          type: boolean
  securitySchemes:
    apiKey:
      type: apiKey
      name: api-key
      in: header
