{"openapi":"3.0.1","info":{"title":"Publish API v2","version":"2.0.3","x-olp-service":{"name":"publish","version":"v2"}},"externalDocs":{"description":"The developer guide and related API references are available here.","url":"https://www.here.com/docs/category/data-api"},"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":"Publish API v2 initPublication","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"}},"/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":"Publish API v2 getPublication","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"},"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":"Publish API v2 submitPublication","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"},"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":"Publish API v2 cancelPublication","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"}},"/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":"Publish API v2 uploadPartitions","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"}}},"components":{"schemas":{"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."},"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."},"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"}}}},"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"}}}}},"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.\n\nFor 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).\n"}}}}