HERE Publish API

openapi: 3.2.0
info:
  title: v2 Publish API
  version: 2.0.3
  x-olp-service:
    name: publish
    version: v2
  description: Manage the publishing of data to a catalog. Supports publish to `versioned`, and `volatile` layer types. To publish to 'stream' layer please use Ingest API. See Data API Developer’s Guide in the Documentation section for more information. Note that the full API Paths need to be resolved with lookup service.
servers:
- url: https://use.apilookup.for.a.base.url/
security:
- Bearer: []
tags:
- name: Publish
  description: Manage the publishing of data to a catalog. Supports publish to `versioned`, and `volatile` layer types. To publish to 'stream' layer please use Ingest API. See Data API Developer’s Guide in the Documentation section for more information. Note that the full API Paths need to be resolved with lookup service.
paths:
  /publications:
    post:
      tags:
      - Publish
      summary: Initialize a new publication
      description: Initializes a new publication for publishing metadata. Determines the publication type based on the provided layer IDs. A publication can only consist of layer IDs that have the same layer type. For example, you can have a publication for multiple layers of type `versioned`, but you cannot have a single publication that publishes to both `versioned` and `volatile` layers. In addition, you may only have one `versioned` publication in process at a time. The body field `versionDependencies` is optional and is used for `versioned` layers to declare version dependencies.
      operationId: PublishAPIV2InitPublication
      parameters:
      - 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.
        schema:
          type: string
      requestBody:
        description: Fields to initialize a publication.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Publication'
        required: true
      responses:
        '200':
          description: New publication created.
          headers:
            Location:
              description: The location of the newly created publication.
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Publication'
        '400':
          description: Bad request, it is impossible to publish to all the requested layers in one single publication.
          content: {}
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '409':
          description: Conflict with an another active publication.
          content: {}
      x-olp-access-type: resource
      x-codegen-request-body-name: body
      x-operation-id-source: normalized
      x-operation-id-original: Publish API v2 initPublication
  /publications/{publicationId}:
    get:
      tags:
      - Publish
      summary: Gets a publication
      description: 'Returns the details of the specified publication. Publication can be in one of these states: Initialized, Submitted, Cancelled, Failed, Succeeded, Expired. See Data API Developer’s Guide in the Documentation section for the publication state diagram.'
      operationId: PublishAPIV2GetPublication
      parameters:
      - name: publicationId
        in: path
        description: The ID of the publication to retrieve.
        required: true
        schema:
          type: string
      - 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 and contain only alphanumeric ASCII characters [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        schema:
          type: string
      responses:
        '200':
          description: The publication details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Publication'
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Publication not found.
          content: {}
      x-olp-access-type: resource
      x-operation-id-source: normalized
      x-operation-id-original: Publish API v2 getPublication
    put:
      tags:
      - Publish
      summary: Submits a publication
      description: Submits the publication and initiates post processing if necessary. Publication state becomes `Submitted` directly after submission and `Succeeded` after successful processing. See Data API Developer’s Guide in the Documentation section for complete publication states diagram.
      operationId: PublishAPIV2SubmitPublication
      parameters:
      - name: publicationId
        in: path
        description: ID of publication to submit.
        required: true
        schema:
          type: string
      - 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 and contain only alphanumeric ASCII characters [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        schema:
          type: string
      responses:
        '204':
          description: Publication was submitted successfully.
          content: {}
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Publication not found.
          content: {}
      x-olp-access-type: resource
      x-operation-id-source: normalized
      x-operation-id-original: Publish API v2 submitPublication
    delete:
      tags:
      - Publish
      summary: Cancels a publication
      description: Cancels a publication if it has not yet been submitted. Will fail if attempting to cancel a submitted publication. This allows the specified publication to be abandoned. See Data API Developer’s Guide in the Documentation section for publication states diagram and all possible publication states transitions.
      operationId: PublishAPIV2CancelPublication
      parameters:
      - name: publicationId
        in: path
        description: The ID of the publication to cancel.
        required: true
        schema:
          type: string
      - 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 and contain only alphanumeric ASCII characters [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        schema:
          type: string
      responses:
        '204':
          description: Publication was cancelled successfully.
          content: {}
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Publication not found.
          content: {}
      x-olp-access-type: resource
      x-operation-id-source: normalized
      x-operation-id-original: Publish API v2 cancelPublication
  /layers/{layerId}/publications/{publicationId}/partitions:
    post:
      tags:
      - Publish
      summary: Upload partitions
      description: Upload partitions to the given layer. Dependending on the publication type, post processing may be required before the partitions are published. For better performance batch your partitions (e.g. 10000 per request), rather than uploading them individually.
      operationId: PublishAPIV2UploadPartitions
      parameters:
      - name: layerId
        in: path
        description: The ID of the layer to publish to.
        required: true
        schema:
          type: string
      - name: publicationId
        in: path
        description: The ID of publication to publish to.
        required: true
        schema:
          type: string
      - 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 and contain only alphanumeric ASCII characters [A-Za-z0-9]. Grouping billing records by billing tag will be available in future releases.
        schema:
          type: string
      requestBody:
        description: Publication partitions. fields
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishPartitions'
        required: true
      responses:
        '204':
          description: Partitions successfully submitted.
          content: {}
        '400':
          description: Bad request, trying to publish partitions with fields not applicable or mandatory fields missing, given the layer type.
          content: {}
        '401':
          description: Unauthorized.
          content: {}
        '403':
          description: Forbidden.
          content: {}
        '404':
          description: Publication not found.
          content: {}
      x-olp-access-type: resource
      x-codegen-request-body-name: body
      x-operation-id-source: normalized
      x-operation-id-original: Publish API v2 uploadPartitions
components:
  schemas:
    PublishPartition:
      required:
      - partition
      - dataHandle
      type: object
      properties:
        partition:
          type: string
          pattern: '[a-zA-Z0-9_\-\.:]'
          description: A key that specifies the partition that the content is related to. It is required. If the layer's partitioning scheme is set to `heretile`, the partition key is the tile key. The maximum length of the partition key is 500 characters.
          example: '314010583'
        checksum:
          type: string
          description: The checksum of the content published to Blob API, applicable when the layer storage volume type is `durable` and therefore the content is constant over time. The algorithm used to calculate the checksum is user specific. Algorithms that you can use are, for example, MD5 or SHA1. This is not a secure hash, so you should only use it to detect changes in content.
          format: '[0-9a-fA-F]+'
          example: ff7494d6f17da702862e550c907c0a91
        compressedDataSize:
          type: integer
          description: The compressed size in bytes of the content published to Blob API, applicable when the layer storage volume type is `durable` and therefore the content is constant over time. Applicable when Content-Encoding is set to gzip when uploading and downloading data in the Blob API.
          format: int64
          example: 152417
        dataSize:
          type: integer
          description: The nominal size in bytes of the content published to Blob API, applicable when the layer storage volume type is `durable` and therefore the content is constant over time. When compression is enabled, this is the size of the uncompressed content.
          format: int64
          example: 250110
        dataHandle:
          type: string
          description: The handle created when uploading the content to the Blob API, that is used to retrieve the content at a later stage.
          example: 1b2ca68f-d4a0-4379-8120-cd025640510c
        crc:
          type: string
          description: User provided CRC of the partition data in bytes. Should be lowercase.
          example: c3f276d7
      description: Metadata describing the partition being published.
    PublishPartitions:
      type: object
      properties:
        partitions:
          type: array
          description: Array of partitions.
          items:
            $ref: '#/components/schemas/PublishPartition'
    Details:
      type: object
      properties:
        state:
          type: string
          description: "The state of the publication.\n * `initialized` - The publication is active and able to receive partitions. The publication can also be submitted while in this state. If you cancel the publication while it is in this state all uploaded partitions are discarded and a new publication is created. An initialized publication expires after a period of inactivity.\n * `submitted` - The publication is active and is processing the uploaded partitions. When a publication is in this state you cannot upload more partitions to the publication. You cannot cancel the publication at this point. It can only succeed, fail, or expire.\n * `cancelled` - The publication was cancelled, either by a cancel request from a user or by initializing a new publication while this one was in the `initialized` state.\n * `succeeded` - The publication was successfully processed.\n * `failed` - The publication failed due to an error. The error is provided in the `message` field.\n * `expired` - The publication has expired due to inactivity."
          readOnly: true
          enum:
          - initialized
          - submitted
          - cancelled
          - failed
          - succeeded
          - expired
        message:
          type: string
          description: A message describing the state.
          readOnly: true
          example: Publication initialized
        started:
          type: integer
          description: The time when the publication started, expressed as the number of milliseconds since the Unix epoch.
          format: int64
          readOnly: true
          example: 1523459129829
        modified:
          type: integer
          description: The time when the publication was last modified, expressed as the number of milliseconds since the Unix epoch.
          format: int64
          readOnly: true
          example: 1523459129829
        expires:
          type: integer
          description: The time when the publication expires, expressed as the number of milliseconds since the Unix epoch.
          format: int64
          readOnly: true
          example: 1523459129829
      description: Details of the publication.
    VersionDependency:
      type: object
      properties:
        direct:
          type: boolean
          description: Indicates the type of data dependency. If this value is set to false, this dependency is an indirect dependency. This means that data from this catalog was not directly used by a data processing pipeline to update the current version of the catalog. Instead, the data was only used by upstream pipelines to generate the input data for a data processing pipeline.
          example: true
        hrn:
          type: string
          description: The HERE Resource Name (HRN) of the catalog that the publication depends on.
          example: hrn:here:data::olp-here:my-catalog
        version:
          type: integer
          description: The version of the catalog metadata that the publication depends on.
          format: int64
          example: 1
      description: Metadata about any dependencies on other catalogs that the publication may have.
    Publication:
      type: object
      properties:
        id:
          type: string
          description: The ID of the publication.
          readOnly: true
          example: 34bc2a16-0373-4157-8ccc-19ba08a6672b
        details:
          $ref: '#/components/schemas/Details'
        layerIds:
          type: array
          items:
            type: string
            description: The ID of a layer in the publication
            example: my-layer
        catalogVersion:
          type: integer
          description: The current version of the catalog. If this is the catalog's first publication, the version is `-1`. After the first publication, the catalog version becomes 0. Each subsequent publication increments the catalog version by 1.
          format: int64
          readOnly: true
          example: 1
        versionDependencies:
          type: array
          description: The upstream version dependencies for the publication.
          items:
            $ref: '#/components/schemas/VersionDependency'
  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