openapi: 3.2.0
info:
  title: v1 Volatile Blob API
  description: The `volatile-blob` service supports the upload and retrieval of volatile data from the storage of a catalog.
  contact: {}
  version: 1.0.3
  x-olp-service:
    name: volatile-blob
    version: v1
servers:
- url: //use.apilookup.for.a.base.url/
security:
- Bearer: []
tags:
- name: volatile-blob
  description: Upload and retrieve large volumes of data
paths:
  /layers/{layerId}/data/{dataHandle}:
    get:
      tags:
      - volatile-blob
      summary: Gets a volatile blob
      description: Retrieves a volatile data blob from storage.
      operationId: Volatile Blob API v1 getVolatileBlob
      parameters:
      - name: layerId
        in: path
        description: The ID of the parent layer for this volatile data blob.
        required: true
        schema:
          type: string
        x-example: my-volatile-layer
      - name: dataHandle
        in: path
        description: The data handle identifies a specific volatile data blob so that you can get that blob's contents.
        required: true
        schema:
          type: string
        x-example: '5023993'
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alpha/numeric ASCII characters [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        required: false
        schema:
          type: string
        x-example: myBillingTag
      responses:
        '200':
          description: OK - Response includes a blob
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '204':
          description: Blob is empty
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationMessage'
        '404':
          description: Not Found - no blob is associated with this dataHandle
      x-olp-access-type: resource
    head:
      tags:
      - volatile-blob
      summary: Checks if a data handle exists
      description: Checks if a volatile blob exists for the requested data handle.
      operationId: Volatile Blob API v1 checkHandleExists
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer that the volatile blob belongs to.
        required: true
        schema:
          type: string
        x-example: my-volatile-layer
      - name: dataHandle
        in: path
        description: The data handle identifies a specific volatile blob so that you can get that blob's contents.
        required: true
        schema:
          type: string
        x-example: '5023993'
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alpha/numeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        required: false
        schema:
          type: string
        x-example: myBillingTag
      responses:
        '200':
          description: OK - dataHandle exists
          content:
            application/octet-stream:
              schema:
                type: string
                format: byte
        '204':
          description: DataHandle exists but blob is empty
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationMessage'
        '404':
          description: Not Found - dataHandle doesn't exist
      x-olp-access-type: resource
    patch:
      tags:
      - volatile-blob
      summary: Modifies ttl for a specific volatile data blob
      description: Modify ttl of the volatile data blob in the underlying storage mechanism (volume).
      operationId: Volatile Blob API v1 patchVolatileBlob
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer that the volatile data blob belongs to.
        required: true
        schema:
          type: string
        x-example: my-volatile-layer
      - name: dataHandle
        in: path
        description: The data handle (ID) represents an identifier for the volatile data blob.
        required: true
        schema:
          type: string
        x-example: '5023993'
      - name: X-Replicate
        in: header
        description: If set to true, it indicates the request is a replication call. It is not required for user to set it manually
        required: false
        schema:
          type: string
        x-example: 'false'
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alpha/numeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        required: false
        schema:
          type: string
        x-example: myBillingTag
      requestBody:
        description: Modify ttl value of the blob
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchProperties'
      responses:
        '204':
          description: No Content - A new ttl was set
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationMessage'
        '404':
          description: Not Found
      x-olp-access-type: resource
    put:
      tags:
      - volatile-blob
      summary: Publishes a volatile data blob
      description: Persists the volatile data blob in the underlying storage mechanism (volume).
      operationId: Volatile Blob API v1 putVolatileBlob
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer that the volatile data blob belongs to.
        required: true
        schema:
          type: string
        x-example: my-volatile-layer
      - name: dataHandle
        in: path
        description: The data handle (ID) represents an identifier for the volatile data blob.
        required: true
        schema:
          type: string
        x-example: '5023993'
      - name: X-Replicate
        in: header
        description: If set to true, it indicates the request is a replication call. It is not required for user to set it manually
        required: false
        schema:
          type: string
        x-example: 'false'
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alpha/numeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        required: false
        schema:
          type: string
        x-example: myBillingTag
      requestBody:
        description: 'The data to upload as part of the blob. Size limit: 2 MB'
        required: true
        content:
          application/json:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: OK - A new blob was uploaded
        '204':
          description: No Content - An existing blob was updated
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationMessage'
        '404':
          description: Not Found
        '507':
          description: Volatile layer out of space
      x-olp-access-type: resource
    delete:
      tags:
      - volatile-blob
      summary: Deletes a volatile data blob
      description: Deletes a volatile data blob from the underlying storage mechanism (volume).
      operationId: Volatile Blob API v1 deleteVolatileBlob
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer that the volatile data blob belongs to.
        required: true
        schema:
          type: string
        x-example: my-volatile-layer
      - name: dataHandle
        in: path
        description: The data handle (ID) represents an identifier for the volatile data blob which contents will be deleted.
        required: true
        schema:
          type: string
        x-example: '5023993'
      - name: X-Replicate
        in: header
        description: If set to true, it indicates the request is a replication call. It is not required for user to set it manually
        required: false
        schema:
          type: string
        x-example: 'false'
      - name: billingTag
        in: query
        description: Billing Tag is an optional free-form tag which is used for grouping billing records together. If supplied, it must be between 4 - 16 characters, contain only alpha/numeric ASCII characters  [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        required: false
        schema:
          type: string
        x-example: myBillingTag
      responses:
        '204':
          description: Deleted - the data blob was successfully deleted.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationMessage'
        '404':
          description: Not Found - data blob with the specified data handle does not exist
      x-olp-access-type: resource
components:
  schemas:
    PatchProperties:
      type: object
      properties:
        ttl:
          type: integer
          format: int64
          example: 3600000
          description: The expiry time in milliseconds. Data is automatically removed after the specified time limit has elapsed. The TTL value must be between 60000 (1 minute) and 604800000 (7 days).
    AuthenticationMessage:
      properties:
        error:
          type: string
          description: Error message
          readOnly: true
          example: Unauthorized
        error_description:
          type: string
          description: Error description
          readOnly: true
          example: Token Validation Failure - invalid time in token
      description: HTTP unauthenticated error message thrown by the service.
      type: object
    AuthorizationMessage:
      properties:
        error:
          type: string
          description: Error message
          readOnly: true
          example: Forbidden
        error_description:
          type: string
          description: Error description
          readOnly: true
          example: These credentials do not authorize access. Please contact your customer representative or submit a request here https://developer.here.com/contact-us to upgrade your account. You can also get valid credentials by registering for a free trial license on https://developer.here.com.
      description: HTTP unauthorized error message thrown by the service.
      type: object
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'A token obtained from a separate endpoint using client credentials and an OAuth 1.0a HMAC-SHA256 signed request.


        For more information on how to get a bearer token, see the [Identity & Access Management Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html).

        '
externalDocs:
  description: The developer guide and related API references are available here.
  url: https://www.here.com/docs/category/data-api