openapi: 3.2.0 info: title: Blob API v2 By Key API description: The `blob` service supports the upload and retrieval of large volumes of data from the storage of a catalog. contact: {} version: 2.0.2 x-olp-service: name: blob version: v2 servers: - url: https://use.apilookup.for.a.base.url/ security: - Bearer: [] tags: - name: by-key description: Upload and retrieve large volumes of data by key paths: /layers/{layerId}/keys/{key}: head: tags: - by-key summary: Checks if a key exists and get object metadata description: Checks if a blob exists for the requested key. You can also use it to fetch object metadata. operationId: Blob API v2 getBlobMetadataByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/key' responses: '200': description: OK - key exists. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' Content-Length: $ref: '#/components/headers/Content-Length' Last-Modified: $ref: '#/components/headers/Last-Modified' Content-Type: $ref: '#/components/headers/Content-Type' Content-Encoding: $ref: '#/components/headers/Content-Encoding' content: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource get: tags: - by-key summary: Gets a blob description: Retrieves a blob from storage. operationId: Blob API v2 getBlobByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/key' - name: accessType in: query description: 'Define preferred blob access type, possible values are: `inlineAccess` and `storageLayerAccess`. `inlineAccess` standard way to deliver blob content within the http response. If `storageLayerAccess` is specified then Blob Service can return http redirect to retrieve blob content from an alternative location, it can be either presigned url to AWS S3 or Azure Blob or similar service. On following redirect client should omit Authorization header.' required: false schema: type: string items: type: string enum: - inlineAccess - storageLayerAccess - name: Range in: header description: 'Use this parameter to resume download of a large response when there is a connection issue between the client and server, or to fetch a specific slice of the blob. To resume download after a connection issue, specify a single byte range offset as follows: `Range: bytes=10-`. To fetch a specific slice of the blob, specify a slice as follows: `Range: bytes=10-100`. This parameter is compliant with [RFC 7233](https://tools.ietf.org/html/rfc7233), but note that this parameter only supports a single byte range. You can also specify the `range` parameter as a query parameter, for example `range=bytes=10-`.' schema: type: string responses: '200': description: OK - response includes a blob. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' Content-Length: $ref: '#/components/headers/Content-Length' Last-Modified: $ref: '#/components/headers/Last-Modified' Content-Type: $ref: '#/components/headers/Content-Type' Content-Encoding: $ref: '#/components/headers/Content-Encoding' content: '*/*': schema: type: string format: binary example: blob contents '206': description: Partial Content - indicates response to the range query as per [RFC 7233](https://tools.ietf.org/html/rfc7233). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: '*/*': schema: type: string format: binary example: partial blob contents '307': description: Temporary redirect to retrieve blob content from an alternative location. content: {} '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '416': description: Range is not valid - indicates errors in the range parameter as per [RFC 7233](https://tools.ietf.org/html/rfc7233). headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource put: tags: - by-key summary: Publishes a data blob or copies an existing blob description: Persists the data blob up to 192 MB. When the operation completes successfully, there is no guarantee that the data blob will be immediately available, although in most cases, it will be. To check if the data blob is available, use the ´HEAD´ method. The maximum key length is 450 characters. operationId: Blob API v2 putBlobByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/key' - name: source in: query description: Copy an existing object, instead of uploading a new one. If this parameter is present, the request payload must be empty. required: false schema: type: string - name: Content-Length in: header description: 'This header relates to upload only. Size of the entity-body, in bytes. For more information, see [RFC 7230, section 3.3.2: Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2).' required: false schema: type: integer format: int64 example: 325 - name: Content-Type in: header description: 'This header relates to upload only. A standard MIME type describing the format of the blob data. For more information, see [RFC 2616, section 14.17: Content-Type](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17). The value of this header must match the content type specified in the `contentType` field when the multipart upload was initialized, and this content type must also match the content type specified in the layer''s configuration.' required: false schema: type: string example: application/octet-stream - name: Content-Encoding in: header description: 'Content-encoding of the object. This header is optional. For more information, see [RFC 2616, section 14.11: Content-Encoding](https://tools.ietf.org/html/rfc2616#section-14.11).' required: false schema: type: string example: gzip - $ref: '#/components/parameters/digestHeader' requestBody: description: Request body. Must be empty when copying an object using the `source` parameter. content: '*/*': schema: type: string format: binary required: false responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/EntityTooLarge' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource delete: tags: - by-key summary: Deletes a data blob description: Deletes a data blob. operationId: Blob API v2 deleteBlobByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/key' responses: '202': description: Accepted - the data blob was successfully deleted. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource post: tags: - by-key summary: Starts a multipart upload description: Publishes large data blobs where the data payload needs to be split into multiple parts. The multipart upload start is to be followed by the individual parts upload and completed with a call to complete the upload. The limit of the blob uploaded this way is 500GB. Max key length is 450 characters. operationId: Blob API v2 startMultipartUploadByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/key' requestBody: description: An object that contains metadata of the uploaded object. required: true content: application/json: schema: $ref: '#/components/schemas/MultipartUploadByKeyMetadata' responses: '200': description: OK - the new multipart upload was successfully started. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/MultipartInitResponse' '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource /layers/{layerId}/keysMultipart/{multipartToken}: get: tags: - by-key summary: Gets the status of a multipart upload description: Gets the status of a multipart upload. The status can be received only when the upload has been completed. operationId: Blob API v2 getMultipartUploadStatusByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/multipartToken' responses: '200': description: OK headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/MultipartKeyUploadStatus' '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource put: tags: - by-key summary: Completes a multipart upload description: Call this API when all parts have been uploaded. operationId: Blob API v2 completeMultipartUploadByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/multipartToken' requestBody: description: The part IDs uploaded in this multipart upload which should be used in the resulting blob. content: application/json: schema: $ref: '#/components/schemas/MultipartCompletePayload' required: false responses: '204': description: No Content headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource delete: tags: - by-key summary: Cancels a multipart upload description: Cancels an entire multipart upload operation. You can only cancel a multipart upload before it has been completed. operationId: Blob API v2 cancelMultipartUploadByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/multipartToken' responses: '202': description: Accepted - the data blob was successfully deleted. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource /layers/{layerId}/keysMultipart/{multipartToken}/parts: post: tags: - by-key summary: Uploads a part or creates a new part from part of an existing blob description: 'Upload or copy a single part of a multipart upload or multipart copy for the blob. Every part except the last one must have a minimum 5 MB of data and maximum of 96 MB. The length of every part except the last must be a multiple of 1MB (1024KB). The maximum number of parts is 10,000.' operationId: Blob API v2 uploadPartByKey parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/multipartToken' - name: partNumber in: query description: This parameter relates to upload and copy. The number of the part for the multipart upload or copy. The numbers of the upload parts must start from 1, be no greater than 10,000 and be consecutive. Parts uploaded with the same `partNumber` are overridden. Do not reuse the same `partNumber` when retrying an upload or copy in an error situation (network problems, 4xx or 5xx responses). Reusing the same `partNumber` in a retry may cause the publication to fail. required: true schema: type: integer format: int32 - name: Content-Length in: header description: 'This header relates to upload only. Size of the entity-body, in bytes. For more information, see [RFC 7230, section 3.3.2: Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2).' required: false schema: type: integer format: int64 example: 325 - name: Content-Type in: header description: 'This header relates to upload only. A standard MIME type describing the format of the blob data. For more information, see [RFC 2616, section 14.17: Content-Type](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17). The value of this header must match the content type specified in the `contentType` field when the multipart upload was initialized, and this content type must also match the content type specified in the layer''s configuration.' required: false schema: type: string example: application/octet-stream - name: source in: query description: Copy part from an existing object, use `range` to specify which parts of the object to copy. required: false schema: type: string - name: Range in: header description: 'This header/parameter relates to object copy using the ''source'' parameter. Use this parameter to copy a specific slice of the blob like this: `Range: bytes=0-1048575`. This parameter is compliant with [RFC 7233](https://tools.ietf.org/html/rfc7233), but note that this parameter only supports a single byte range and both `begin` and `end` values of the range must be specified. The range `begin` value must be multiple of 1MB (1024KB). The length of every part except the last must be a multiple of 1MB (1024KB). The `range` parameter can also be specified as a query parameter, for example `range=bytes=0-1048575`.' schema: type: string - $ref: '#/components/parameters/digestHeader' requestBody: description: The body relates to upload only. The data to upload as part of the blob. content: '*/*': schema: type: string format: binary description: request body required: false responses: '200': description: OK - part was uploaded successfully headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/PartId' '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '413': $ref: '#/components/responses/EntityTooLarge' '416': $ref: '#/components/responses/RangeNotSatisfiable' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource /layers/{layerId}/keys: get: tags: - by-key summary: List keys description: List virtual directory-like structure created from keys in the storage where '/' is used as a separator. operationId: Blob API v2 listKeys parameters: - $ref: '#/components/parameters/layerId' - $ref: '#/components/parameters/parent' - $ref: '#/components/parameters/pageToken' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/deep' responses: '200': description: OK - Response includes a list of keys. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/KeysListResponse' '400': $ref: '#/components/responses/UserError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServerError' '504': $ref: '#/components/responses/ServerError' x-olp-access-type: resource components: schemas: MultipartCompletePayloadPart: type: object required: - id - number properties: id: type: string description: The identifier assigned by the system to identify the uploaded part. The `id` is returned by the upload part operation after successfully uploading a part. example: 1a6ef.... number: type: integer description: The number of the part of the multipart upload. This is the same number used in the `partNumber` parameter in the upload part operation. If an error occurs during upload, do not reuse the `partNumber` when retrying the upload. format: int32 example: 1 MultipartKeyUploadStatus: type: object required: - status properties: status: type: string description: The status of the multipart upload. example: completed enum: - failed - processing - completed description: Describes a status of the multipart upload. KeysListResponse: type: object required: - items properties: pageToken: type: string description: Page token to fetch the next page. items: type: array items: $ref: '#/components/schemas/KeysListObjectItemResponse' description: Paginated response of keys and common prefixes. PartId: type: object required: - id properties: id: type: string description: The identifier assigned by the system to identify the uploaded part. example: 1a6ef.... MultipartUploadByKeyMetadata: type: object required: - contentType properties: contentType: type: string example: application/json description: Content type of the uploaded object. contentEncoding: type: string example: gzip description: Content encoding of the uploaded object. description: Multipart upload metadata by key MultipartInitResponse: type: object required: - multipartToken properties: multipartToken: type: string description: The identifier of the multipart upload (token). example: 7767cf80... description: The identifier of the multipart upload (token). KeysListObjectItemResponse: type: object description: Object or common prefix stored in Object Store layer. required: - name - type properties: name: type: string description: Name of the object/common prefix. example: file1.txt size: type: integer format: int64 description: Object size in bytes or omitted if the `type` field is `commonPrefix`. example: 1024 lastModified: type: string format: date-time example: '2019-12-10T12:20:54Z' description: Last modified date and time in RFC 3339 format or omitted if the `type` field is `commonPrefix`. type: type: string example: object description: Indicates whether the item is object or common prefix. enum: - object - commonPrefix MultipartCompletePayload: type: object properties: parts: type: array items: $ref: '#/components/schemas/MultipartCompletePayloadPart' ValidationError: type: object required: - title - status properties: title: type: string description: Error example: Input data failed validation status: type: integer description: Unexpected server error example: 400 code: type: string description: Error. example: E215101 message: type: string description: Unexpected server error example: The input data in question does not meet validation rules. correlationId: type: string description: Unique request ID example: 4199533b-6290-41db-8d79-edf4f4019a74 ServerError: type: object properties: title: type: string description: Error. example: Input data failed validation. status: type: integer description: Unexpected Server error. example: 400 code: type: string description: Error. example: E215101 message: type: string description: Unexpected server error example: Unexpected server error correlationId: type: string description: Unique request ID example: 4199533b-6290-41db-8d79-edf4f4019a74 headers: X-Correlation-ID: description: Unique ID to correlate client request with server response. schema: type: string example: 4199533b-6290-41db-8d79-edf4f4019a74 Last-Modified: description: Last modified date and time. For more information, see [RFC 3339](https://tools.ietf.org/html/rfc3339) or omitted if the `type` field is `commonPrefix`. schema: type: string format: date-time example: '2019-12-10T12:20:54Z' Content-Type: description: 'A standard MIME type describing the format of the blob data. For more information, see [RFC 2616, section 14.17: Content-Type](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17).' example: application/json schema: type: string Content-Length: description: 'Size of the entity-body, in bytes. For more information, see [RFC 7230, section 3.3.2: Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2).' schema: type: integer format: int64 example: 325 Content-Encoding: description: 'Content-encoding of the object. This header is optional. For more information, see [RFC 2616, section 14.11: Content-Encoding](https://tools.ietf.org/html/rfc2616#section-14.11)' example: gzip schema: type: string parameters: key: name: key in: path description: 'The key identifies a specific blob so that you can get that blob''s contents. Key can only contain allowed characters: a-zA-Z0-9.[]=(){}/_-`.' required: true schema: type: string pattern: '[a-zA-Z0-9.\[\]=(){}/_\-]{1,450}' minLength: 1 maxLength: 450 limit: name: limit in: query description: Number of results to return per page. schema: type: integer format: int32 layerId: name: layerId in: path description: The ID of the parent layer for this blob. required: true schema: type: string digestHeader: name: X-HERE-Digest in: header description: "This header can be used as a data integrity check to verify that the data received by the server is the same data that was originally sent by the client. \nThis header specifies the lowercase Hex encoded 32-bit CRC32C checksum of the object or 128-bit MD5 digest or 160-bit SHA1 digest or 256-bit SHA256 digest.\nYou can choose one of the following Secure Hash Algorithms (SHA) or Cyclic Redundancy Check (CRC) checksum algorithms to calculate the digest value:\n - CRC-32C\n - MD5\n - SHA1\n - SHA256\n\nValue of the header is a combination algorithm name and digest in following format: \"Algorithm:Digest\".\nIf the digest values calculated on the client side doesn't match to the digest on the server side, server generates Bad Request error." schema: type: string example: CRC-32C:f23c6e4e multipartToken: name: multipartToken in: path description: The identifier of the multipart upload (token). This token is returned when the multipart upload is initiated. required: true schema: type: string parent: name: parent in: query description: Common prefix to a list. schema: type: string pageToken: name: pageToken in: query description: If specified, will return the specific page based on the token. schema: type: string deep: name: deep in: query description: Use deep (recursive) listing of objects instead of hierarchical listing. Deep listing will not produce any common prefixes. schema: type: boolean responses: NotFound: description: Not Found - the specified resource was not found headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} ServerError: description: Server unavailable or internal server error headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/ServerError' Forbidden: description: Forbidden - the specific account doesn't have correct privileges to perform the operation headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} Unauthorized: description: Unauthorized - the request didn't provide correct authentication details headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} RangeNotSatisfiable: description: Request range is not valid - request made from a client has invalid range. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} EntityTooLarge: description: Request entity too large - request made from a client is too large to be processed by the server. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: {} UserError: description: User Error - Invalid input is provided headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/ValidationError' 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