app/src/docs/v1.api-spec.yaml
---
openapi: 3.0.2
info:
version: 1.0.0
title: Common Object Management Service (COMS)
description: A microservice for managing access control to S3 Objects
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
name: NR Common Service Showcase
email: NR.CommonServiceShowcase@gov.bc.ca
servers:
- url: /api/v1
description: This Server
security:
- BasicAuth: []
- BearerAuth: []
OpenID: []
tags:
- name: Bucket
description: Operations for managing S3 Bucket(s).
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#bucket
- name: Metadata
description: Operations for managing Metadata for S3 Objects.
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#metadata
- name: Object
description: Operations directly influencing an S3 Object.
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#object
- name: Permission
description: Operations for managing S3 permissions.
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#permission
- name: Sync
description: >-
Operations for syncing existing buckets and objects. Ensures that external
S3 modifications are eventually correctly tracked by COMS.
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#sync
- name: Tagging
description: Operations for managing Tags for S3 Objects.
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#tag
- name: User
description: Operations to list valid queryable users and identity providers.
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes#user
- name: Version
description: Operations to list object versions.
externalDocs:
url: >-
https://github.com/bcgov/common-object-management-service/wiki/Endpoint-Notes
paths:
/bucket:
put:
summary: Creates a bucket
description: >-
Creates a bucket record. Bucket should exist in S3. If the set of
`bucket`, `endpoint` and `key` match an existing record, the user will
be added to that existing bucket with the provided permissions instead of
generating a new bucket record. This endpoint can be used to grant the current user
permission to upload to a new or existing bucket.
operationId: createBucket
tags:
- Bucket
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Request-CreateBucket"
responses:
"201":
description: Returns inserted DB bucket record
content:
application/json:
schema:
$ref: "#/components/schemas/DB-Bucket"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
$ref: "#/components/responses/Conflict"
default:
$ref: "#/components/responses/Error"
get:
summary: Search for buckets
description: >-
Returns a list of buckets matching all search criteria across all bucket
records
operationId: searchBuckets
tags:
- Bucket
parameters:
- $ref: "#/components/parameters/Query-BucketId"
- $ref: "#/components/parameters/Query-Active"
- $ref: "#/components/parameters/Query-Key"
- $ref: "#/components/parameters/Query-BucketName"
responses:
"200":
description: Returns an array of buckets
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-Bucket"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/bucket/{bucketId}:
head:
summary: Checks if a bucket exists in S3
description: Returns either a 204 or 403 if user lacks permissions
operationId: headBucket
tags:
- Bucket
parameters:
- $ref: "#/components/parameters/Path-BucketId"
responses:
"204":
description: Returns object headers
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
get:
summary: Returns a bucket
description: Returns a bucket record based on bucketId
operationId: readBucket
tags:
- Bucket
parameters:
- $ref: "#/components/parameters/Path-BucketId"
responses:
"200":
description: Returns bucket
content:
application/json:
schema:
$ref: "#/components/schemas/DB-Bucket"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
patch:
summary: Updates a bucket
description: Updates the bucket record
operationId: updateBucket
tags:
- Bucket
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Request-UpdateBucket"
parameters:
- $ref: "#/components/parameters/Path-BucketId"
responses:
"200":
description: Returns updated bucket
content:
application/json:
schema:
$ref: "#/components/schemas/DB-Bucket"
"403":
$ref: "#/components/responses/Forbidden"
"409":
$ref: "#/components/responses/Conflict"
default:
$ref: "#/components/responses/Error"
delete:
summary: Deletes a bucket
description: >-
Deletes the bucket record based on bucketId. This request does not
dispatch an S3 operation to request the deletion of the associated
bucket.
operationId: deleteBucket
tags:
- Bucket
parameters:
- $ref: "#/components/parameters/Path-BucketId"
responses:
"204":
description: Returns no content success
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/bucket/{bucketId}/child:
put:
summary: Creates a child bucket
description: >-
Creates a child bucket record relative to the parent bucket and copies
the majority of the credential values. Bucket should exist in S3. This
endpoint will report a collision and the bucketId it collided with if
the desired bucket already exists. User requires `MANAGE` permission on
the parent bucket to proceed.
operationId: createBucketChild
tags:
- Bucket
parameters:
- $ref: "#/components/parameters/Path-BucketId"
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/Request-CreateBucketChild"
responses:
"201":
description: Returns inserted DB child bucket record
content:
application/json:
schema:
$ref: "#/components/schemas/DB-Bucket"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
description: Conflict (Request conflicts with server state)
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Response-Conflict"
- type: object
properties:
bucketId:
type: string
description: The bucketId this request is in collision with
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
key:
type: string
description: The derived bucket key
example: foo/bar
"422":
description: Unprocessable Content (Derived bucket key is too long)
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/Response-ValidationError"
- type: object
properties:
key:
type: string
description: The derived bucket key
example: foo/bar
default:
$ref: "#/components/responses/Error"
/bucket/{bucketId}/sync:
get:
summary: Synchronize a bucket
description: >-
Synchronize the contents of an existing bucket with COMS so that it can
track and manage the objects in it. This avoids the need to re-upload
preexisting files through the COMS API. This endpoint does not guarantee
immediately synchronized results. Synchronization latency will be
affected by the remaining number of objects awaiting synchronization.
This endpoint updates the last known successful synchronization request
date when invoked.
tags:
- Sync
operationId: syncBucket
parameters:
- $ref: "#/components/parameters/Path-BucketId"
responses:
"202":
$ref: "#/components/responses/AddedQueueLength"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
/metadata:
get:
summary: Search all metadata
description: >-
Gets a list of metadata matching the given parameters. Multiple
Key/Value pairs can be provided in the headers to narrow down results.
If none are provided the full set of metadata will be returned.
operationId: searchMetadata
tags:
- Metadata
parameters:
- $ref: "#/components/parameters/Header-Metadata"
responses:
"200":
description: Returns an array of matching key/value pairs.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-MetadataKeyValue"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
/object:
put:
summary: Creates an object
description: >-
Creates an object in the bucket specified with bucketId parameter or
default bucket configured. The object will be toggled to private after
this operation. If COMS is running in either 'OIDC' or 'Full' mode, any
objects created with OIDC user authentication will have all object
permissions assigned to them by default. This endpoint will do a best
attempt effort to create the object as requested as long as it does not
already exist in the destination bucket and path. Existing objects
should be managed with the updateObject endpoint instead.
operationId: createObject
tags:
- Object
parameters:
- $ref: "#/components/parameters/Header-ContentDisposition"
- $ref: "#/components/parameters/Header-ContentLength"
- $ref: "#/components/parameters/Header-ContentType"
- $ref: "#/components/parameters/Header-Metadata"
- $ref: "#/components/parameters/Query-TagSet"
- in: query
name: bucketId
description: Uuid representing the bucket
schema:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
requestBody:
description: Raw binary representation of the file
required: true
content:
"*/*":
schema:
type: string
description: >-
Contains the binary representation of the file to upload.
Maximum filesize of 5TB.
format: binary
maxLength: 5497558138880
responses:
"200":
description: Returns the created object data
content:
application/json:
schema:
$ref: "#/components/schemas/Response-ObjectDetails"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
description: Conflict. Bucket already contains the object
content:
application/json:
schema:
$ref: "#/components/schemas/Response-Conflict"
"411":
$ref: "#/components/responses/LengthRequired"
"413":
$ref: "#/components/responses/ContentTooLarge"
"415":
$ref: "#/components/responses/UnsupportedMediaType"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
get:
summary: Search for objects
description: >-
Returns a list of objects matching all search criteria across all known
versions of objects. Search criteria on string attributes will match on
partial results and ignore case sensitivity.
operationId: searchObjects
tags:
- Object
parameters:
- $ref: "#/components/parameters/Header-Metadata"
- $ref: "#/components/parameters/Query-ObjectId"
- $ref: "#/components/parameters/Query-BucketId"
- $ref: "#/components/parameters/Query-Path"
- $ref: "#/components/parameters/Query-Active"
- $ref: "#/components/parameters/Query-DeleteMarker"
- $ref: "#/components/parameters/Query-Latest"
- $ref: "#/components/parameters/Query-Public"
- $ref: "#/components/parameters/Query-MimeType"
- $ref: "#/components/parameters/Query-Name"
- $ref: "#/components/parameters/Query-TagSet"
- $ref: "#/components/parameters/Query-Permissions"
- $ref: "#/components/parameters/Query-Limit"
- $ref: "#/components/parameters/Query-Order"
- $ref: "#/components/parameters/Query-Page"
- $ref: "#/components/parameters/Query-Sort"
responses:
"200":
description: Returns and array of objects
content:
application/json:
schema:
type: array
items:
type: object
allOf:
- $ref: "#/components/schemas/DB-Object"
- type: object
properties:
permissions:
type: array
description: >-
An array of object permissions in the context of the
current user. Yields an empty array if authenticated
via Basic Auth. Property only present if queryparam
`permissions=true` is in request.
items:
type: string
description: An object permission
example: READ
headers:
X-Total-Rows:
schema:
type: integer
description: >-
Total number of objects matching the search query independent of
pagination scope
required: true
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/object/{objectId}:
get:
summary: Returns the object
description: >-
Returns the object as either a direct binary stream, an HTTP 201
containing a direct, temporary pre-signed S3 object URL location, or an
HTTP 302 redirect to a direct, temporary pre-signed S3 object URL
location.
operationId: readObject
tags:
- Object
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-Download"
- $ref: "#/components/parameters/Query-ExpiresIn"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"200":
description: Returns the object
headers:
Content-Disposition:
$ref: "#/components/headers/Content-Disposition"
Content-Length:
$ref: "#/components/headers/Content-Length"
Content-Type:
$ref: "#/components/headers/Content-Type"
ETag:
$ref: "#/components/headers/ETag"
Last-Modified:
$ref: "#/components/headers/Last-Modified"
x-amz-server-side-encryption:
$ref: "#/components/headers/x-amz-server-side-encryption"
x-amz-version-id:
$ref: "#/components/headers/x-amz-version-id"
x-amz-meta-id:
$ref: "#/components/headers/x-amz-meta-id"
x-amz-meta-name:
$ref: "#/components/headers/x-amz-meta-name"
x-amz-meta-*:
description: Any additional metadata key/value pairs added to the object
schema:
type: string
maximum: 255
content:
application/octet-stream:
schema:
type: string
format: binary
"201":
description: Returns a Presigned S3 URL
content:
application/json:
schema:
$ref: "#/components/schemas/Response-PresignedURL"
"302":
$ref: "#/components/responses/S3Found"
"304":
$ref: "#/components/responses/NotModified"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
default:
$ref: "#/components/responses/Error"
head:
summary: Returns object headers
description: Returns S3 and COMS headers for a specific object
operationId: headObject
tags:
- Object
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"204":
description: Returns object headers
headers:
Content-Disposition:
$ref: "#/components/headers/Content-Disposition"
Content-Length:
$ref: "#/components/headers/Content-Length"
Content-Type:
$ref: "#/components/headers/Content-Type"
ETag:
$ref: "#/components/headers/ETag"
Last-Modified:
$ref: "#/components/headers/Last-Modified"
x-amz-server-side-encryption:
$ref: "#/components/headers/x-amz-server-side-encryption"
x-amz-version-id:
$ref: "#/components/headers/x-amz-version-id"
x-amz-meta-id:
$ref: "#/components/headers/x-amz-meta-id"
x-amz-meta-name:
$ref: "#/components/headers/x-amz-meta-name"
x-amz-meta-*:
description: Any additional metadata key/value pairs added to the object
schema:
type: string
maximum: 255
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
put:
summary: Updates an object
description: >-
Updates the object in the configured object storage. If the object
storage supports versioning, a new version will be generated instead of
overwriting the existing contents.
operationId: updateObject
tags:
- Object
parameters:
- $ref: "#/components/parameters/Header-ContentLength"
- $ref: "#/components/parameters/Header-ContentType"
- $ref: "#/components/parameters/Header-Metadata"
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-TagSet"
requestBody:
description: Raw binary representation of the file
required: true
content:
"*/*":
schema:
type: string
description: >-
Contains the binary representation of the file to upload.
Maximum filesize of 5TB.
format: binary
maxLength: 5497558138880
responses:
"200":
description: Returns the updated object data
content:
application/json:
schema:
$ref: "#/components/schemas/Response-ObjectDetails"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
description: Conflict. Bucket does not contain the existing object
content:
application/json:
schema:
$ref: "#/components/schemas/Response-Conflict"
"411":
$ref: "#/components/responses/LengthRequired"
"413":
$ref: "#/components/responses/ContentTooLarge"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
delete:
summary: Deletes an object or a version of object
description: >-
Deletes the specified object (or version) from S3. If the object storage
supports versioning, precise S3 version stack manipulation is supported,
including soft-deletion and soft-restore. Hard-deletions on S3 are also
supported. For more details on general S3 version behavior, visit
https://docs.aws.amazon.com/AmazonS3/latest/userguide/DeletingObjectVersions.html
operationId: deleteObject
tags:
- Object
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"200":
description: Object or version was deleted from object storage and COMS database
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Response-ObjectDeleted"
- $ref: "#/components/schemas/Response-VersionDeleted"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/object/{objectId}/version:
get:
summary: List versions for an object
description: >-
Returns an array of an object's versions, including delete-markers,
ordered by creation date.
operationId: listObjectVersion
tags:
- Version
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
responses:
"200":
description: Returns an array of versions for a specific object
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-Version"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/object/{objectId}/public:
patch:
summary: Sets the public flag of an object
description: >-
Toggles the public property for an object and broadcasts to S3 ACL. Sets
public to false if public query parameter is not specified.
operationId: togglePublic
tags:
- Object
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-Public"
responses:
"200":
description: Returns the object information
content:
application/json:
schema:
$ref: "#/components/schemas/DB-Object"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/object/{objectId}/metadata:
patch:
summary: Adds metadata to an object
description: >-
Creates a copy and new version of the object with the given metadata
added to the object. Multiple Key/Value pairs can be provided in the
header for the metadata. The object will be toggled to private after
this operation.
operationId: addMetadata
tags:
- Metadata
parameters:
- $ref: "#/components/parameters/Header-Metadata"
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"204":
$ref: "#/components/responses/NoContent"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
put:
summary: Replaces metadata of an object
description: >-
Creates a copy and new version of the object with the given metadata
replacing the existing. Multiple Key/Value pairs can be provided in the
header for the metadata. The object will be toggled to private after
this operation.
operationId: replaceMetadata
tags:
- Metadata
parameters:
- $ref: "#/components/parameters/Header-Metadata"
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"204":
$ref: "#/components/responses/NoContent"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
delete:
summary: Delete metadata of an object.
description: >-
Creates a copy and new version of the object with the given metadata
removed. Multiple Key/Value pairs can be provided in the header for the
metadata. If no metadata headers are given then all metadata will be
removed. Metadata headers `name` and `id` are mandatory and will always
persist.
operationId: deleteMetadata
tags:
- Metadata
parameters:
- $ref: "#/components/parameters/Header-Metadata"
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"204":
$ref: "#/components/responses/NoContent"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/object/{objectId}/sync:
get:
summary: Synchronize an existing object
description: >-
Synchronize an existing COMS object so that any changes made externally
(e.g. using an S3 client to upload a new version) are tracked by COMS.
This endpoint does not guarantee immediately synchronized results.
Synchronization latency will be affected by the remaining number of
objects awaiting synchronization. The `lastSyncedDate` attribute will be
asynchronously updated when it performs a successful synchronization
with the S3 bucket
tags:
- Sync
operationId: syncObject
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
responses:
"202":
description: Returns the number of objects that have been added to the queue.
content:
text/plain:
schema:
type: integer
example: 5
description: number of objects added to the queue
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
/object/{objectId}/tagging:
patch:
summary: Adds tags to an object
description: >-
Adds a specified set of tags to the object. Multiple Key/Value pairs can
be provided in the query.
operationId: addTagging
tags:
- Tagging
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-TagSet"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"204":
$ref: "#/components/responses/NoContent"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
$ref: "#/components/responses/Conflict"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
put:
summary: Replaces tags of an object
description: >-
Replace the existing tag-set of an object with the set of given tags.
Multiple Key/Value pairs can be provided in the query.
operationId: replaceTagging
tags:
- Tagging
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-TagSet"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"204":
$ref: "#/components/responses/NoContent"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
delete:
summary: Delete tags of an object.
description: >-
Removes the specified set of tags from the object. Multiple Key/Value
pairs can be provided in the query. All tags in the tag-set will be
removed from the object if no tags are specified.
operationId: deleteTagging
tags:
- Tagging
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-TagSet"
- $ref: "#/components/parameters/Query-S3VersionId"
- $ref: "#/components/parameters/Query-VersionId"
responses:
"204":
$ref: "#/components/responses/NoContent"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/object/metadata:
get:
summary: List metadata for objects
description: >-
Gets a list of metadata matching the given parameters. Multiple
Key/Value metadata pairs can be provided in the query to narrow down
results. If none are provided all metadata will be returned for each
object.
operationId: fetchMetadata
tags:
- Metadata
parameters:
- $ref: "#/components/parameters/Header-Metadata"
- $ref: "#/components/parameters/Query-BucketId"
- $ref: "#/components/parameters/Query-ObjectId"
responses:
"200":
description: Returns an array objects with matching metadata key/value pairs.
content:
application/json:
schema:
type: array
items:
type: object
required:
- objectId
- metadata
properties:
objectId:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
metadata:
type: array
items:
$ref: "#/components/schemas/DB-MetadataKeyValue"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
/object/tagging:
get:
summary: List Tags for objects
description: >-
Gets a list of tags matching the given parameters. Multiple Key/Value
metadata pairs can be provided in the query to narrow down results. If
none are provided all tags will be returned for each object.
operationId: fetchTags
tags:
- Tagging
parameters:
- $ref: "#/components/parameters/Query-BucketId"
- $ref: "#/components/parameters/Query-ObjectId"
- $ref: "#/components/parameters/Query-TagSet"
responses:
"200":
description: Returns an array objects with matching key/value tag pairs.
content:
application/json:
schema:
type: array
items:
type: object
required:
- objectId
- tagset
properties:
objectId:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
tagset:
type: array
items:
$ref: "#/components/schemas/DB-TagKeyValue"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
/permission/bucket:
get:
summary: Searches for bucket permissions
description: >-
Returns an array of buckets and their permissions meeting the filtering
parameters provided. Use `objectPerms=true` in conjunction with a userId
to get an extended bucket list factoring in object inheritance.
operationId: bucketSearchPermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Query-BucketId"
- $ref: "#/components/parameters/Query-UserId"
- $ref: "#/components/parameters/Query-PermCode"
- $ref: "#/components/parameters/Query-ObjectPerms"
responses:
"200":
description: >-
Returns an array of bucketIds and permissions that match the
provided parameters
content:
application/json:
schema:
type: array
items:
anyOf:
- $ref: "#/components/schemas/Response-BucketPerms"
- $ref: "#/components/schemas/Response-BucketPermsWithObject"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/permission/bucket/{bucketId}:
get:
summary: Returns the bucket permissions
description: >-
Returns an array of permissions for a specific bucket meeting the
filtering parameters provided
operationId: bucketListPermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Query-UserId"
- $ref: "#/components/parameters/Path-BucketId"
- $ref: "#/components/parameters/Query-PermCode"
responses:
"200":
description: >-
Returns an array of bucketId/userId/permCode triplets that match the
provided parameters
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-BucketPermission"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
put:
summary: Grants bucket permissions to users
description: >-
Adds permissions for a specific bucket to users by specifying an
arbitrary array of permCode and user tuples. This is an idempotent
operation, so users that already have a requested permission will remain
unaffected. Only permissions successfully added to COMS will appear in
the response.
operationId: bucketAddPermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Path-BucketId"
requestBody:
description: >-
An array of bucket permissions, each containing a `userId` and
`permCode`
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Request-PermissionTuple"
responses:
"201":
description: Returns an array of added permissions
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-BucketPermission"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
delete:
summary: Deletes permissions for a bucket
description: >-
Removes permissions for a specific bucket by optionally specifying a set
of users and subset of permissions to revoke. This is an idempotent
operation, so users that already lack the specified permission(s) will
remain unaffected. Only permissions successfully removed from COMS will
appear in the response. WARNING: Specifying no parameters will delete
all permissions associated with a bucket; it is possible to lock
yourself out of your own bucket!
operationId: bucketRemovePermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Path-BucketId"
- $ref: "#/components/parameters/Query-UserId"
- $ref: "#/components/parameters/Query-PermCode"
responses:
"200":
description: Returns an array of deleted permissions
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-BucketPermission"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/permission/invite:
post:
summary: Creates an invitation token
description: >-
Generates a time-limited invitation token which can be used by an
authenticated user to acquire read permissions to a specific resource.
Optional email-user validation may be specified to ensure the token is
only used by the intended recipient. User requires `MANAGE` permission
for the intended resource to proceed.
operationId: createInvite
tags:
- Permission
requestBody:
description: >-
An object containing at minimum either a `bucketId` or `objectId`
property, but not both.
content:
application/json:
schema:
$ref: "#/components/schemas/Request-CreateInvite"
responses:
"201":
description: Returns the invitation token uuid generated
content:
application/json:
schema:
type: string
description: The invitation token uuid
format: uuid
example: 59aa2c57-2d3d-4e78-99fc-4886457bd8b3
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"409":
$ref: "#/components/responses/Conflict"
default:
$ref: "#/components/responses/Error"
/permission/invite/{token}:
get:
summary: Uses an invitation token
description: >-
Uses a time-limited invitation token assuming the correct user is
authenticated.
operationId: useInvite
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Path-InviteToken"
responses:
"200":
description: Returns an object containing the resource uuid and the type
content:
application/json:
schema:
$ref: "#/components/schemas/Response-InviteResult"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"409":
$ref: "#/components/responses/Conflict"
"410":
$ref: "#/components/responses/Gone"
default:
$ref: "#/components/responses/Error"
/permission/object:
get:
summary: Search for object permissions
description: >-
Returns an array of permissions meeting the filtering parameters
provided. Use `bucketPerms=true` in conjunction with a userId to get an
extended object list factoring in bucket inheritance.
operationId: objectSearchPermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Query-BucketId"
- $ref: "#/components/parameters/Query-ObjectId"
- $ref: "#/components/parameters/Query-UserId"
- $ref: "#/components/parameters/Query-PermCode"
- $ref: "#/components/parameters/Query-BucketPerms"
responses:
"200":
description: >-
Returns an array of objectId/userId/permCode triplets that match the
provided parameters
content:
application/json:
schema:
type: array
items:
anyOf:
- $ref: "#/components/schemas/Response-ObjectPerms"
- $ref: "#/components/schemas/Response-ObjectPermsWithBucket"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/permission/object/{objectId}:
get:
summary: Returns the object permissions
description: >-
Returns an array of object permissions for a specific object meeting the
filtering parameters provided
operationId: objectListPermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-UserId"
- $ref: "#/components/parameters/Query-PermCode"
responses:
"200":
description: >-
Returns an array of objectId/userId/permCode triplets that match the
provided parameters
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-ObjectPermission"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
put:
summary: Grants object permissions to users
description: >-
Adds permissions for a specific object to users by specifying an
arbitrary array of permCode and user tuples. This is an idempotent
operation, so users that already have a requested permission will remain
unaffected. Only permissions successfully added to COMS will appear in
the response.
operationId: objectAddPermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
requestBody:
description: An array of objects, each containing a `permCode` and `userId`
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Request-PermissionTuple"
responses:
"201":
description: Returns an array of added permissions
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-ObjectPermission"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
delete:
summary: Deletes permissions for an object
description: >-
Removes permissions for a specific object by optionally specifying a set
of users and subset of permissions to revoke. This is an idempotent
operation, so users that already lack the specified permission(s) will
remain unaffected. Only permissions successfully removed from COMS will
appear in the response. WARNING: Specifying no parameters will delete
all permissions associated with an object; it is possible to lock
yourself out of your own object!
operationId: objectRemovePermissions
tags:
- Permission
parameters:
- $ref: "#/components/parameters/Path-ObjectId"
- $ref: "#/components/parameters/Query-UserId"
- $ref: "#/components/parameters/Query-PermCode"
responses:
"200":
description: Returns an array of deleted permissions
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-ObjectPermission"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/sync:
get:
summary: Synchronize with the default bucket
description: >-
Synchronize the contents of the default bucket with COMS so that it can
track and manage objects that are already in the bucket. This avoids the
need to re-upload preexisting files through the COMS API. This endpoint
does not guarantee immediately synchronized results. Synchronization
latency will be affected by the remaining number of objects awaiting
synchronization. This endpoint updates the last known successful
synchronization request date when invoked.
operationId: syncDefault
tags:
- Sync
responses:
"202":
$ref: "#/components/responses/AddedQueueLength"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/sync/status:
get:
summary: Get sync queue size
description: Returns the number of objects currently awaiting processing by COMS.
operationId: syncStatus
tags:
- Sync
responses:
"200":
description: Returns the number of objects currently in the queue
content:
text/plain:
schema:
type: integer
example: 5
description: number of objects currently in the queue
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/tagging:
get:
summary: Search all tags
description: >-
Gets a list of tags matching the given parameters. Multiple Key/Value
pairs can be provided in the headers to narrow down results. If none are
provided the full set of tags will be returned.
operationId: searchTags
tags:
- Tagging
parameters:
- $ref: "#/components/parameters/Query-TagSet"
responses:
"200":
description: Returns an array of matching key/value pairs.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-TagKeyValue"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
/user:
get:
summary: Search for users
description: >-
Returns a list of users based on the provided filtering parameters. At
least one query parameter must be present.
operationId: searchUsers
tags:
- User
parameters:
- $ref: "#/components/parameters/Query-UserId"
- $ref: "#/components/parameters/Query-IdentityId"
- $ref: "#/components/parameters/Query-Idp"
- $ref: "#/components/parameters/Query-Username"
- $ref: "#/components/parameters/Query-Email"
- $ref: "#/components/parameters/Query-FirstName"
- $ref: "#/components/parameters/Query-FullName"
- $ref: "#/components/parameters/Query-LastName"
- $ref: "#/components/parameters/Query-Active"
- $ref: "#/components/parameters/Query-UserSearch"
responses:
"200":
description: >-
Returns a JSON object representation of the user matching provided
parameters
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-User"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/user/idpList:
get:
summary: Lists all identity providers
description: Returns a list of all currently known identity providers
operationId: listIdps
tags:
- User
parameters:
- $ref: "#/components/parameters/Query-Active"
responses:
"200":
description: Returns a JSON array of known identity providers
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/DB-IdentityProvider"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
default:
$ref: "#/components/responses/Error"
/version/metadata:
get:
summary: List metadata for versions
description: >-
Gets a metadata matching the given versions. Multiple Key/Value pairs
can be provided in the headers to narrow down results. If none are
provided the full set of metadata will be returned.
operationId: fetchMetadataForVersion
tags:
- Metadata
parameters:
- $ref: "#/components/parameters/Header-Metadata"
- in: query
name: s3VersionId
description: >-
One or an array of version identifiers created in S3. This parameter
is incompatible with `versionId`
schema:
oneOf:
- $ref: "#/components/schemas/S3VersionId"
- type: array
items:
$ref: "#/components/schemas/S3VersionId"
- in: query
name: versionId
description: >-
One or an array of version identifiers created in COMS. This
parameter is incompatible with `s3VersionId`
schema:
oneOf:
- $ref: "#/components/schemas/VersionId"
- type: array
items:
$ref: "#/components/schemas/VersionId"
responses:
"200":
description: Returns an array of versions with matching key/value pairs.
content:
application/json:
schema:
type: array
items:
type: object
required:
- versionId
- metadata
properties:
versionId:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
metadata:
type: array
items:
$ref: "#/components/schemas/DB-MetadataKeyValue"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
/version/tagging:
get:
summary: List tags for versions
description: >-
Gets matching tags for matching versions. Multiple Key/Value pairs can
be provided in the headers to narrow down results. If none are provided
the full set of tags will be returned.
operationId: fetchTagsForVersion
tags:
- Tagging
parameters:
- $ref: "#/components/parameters/Query-TagSet"
- in: query
name: s3VersionId
description: >-
One or an array of version identifiers created in S3. This parameter
is incompatible with `versionId`
schema:
oneOf:
- $ref: "#/components/schemas/S3VersionId"
- type: array
items:
$ref: "#/components/schemas/S3VersionId"
- in: query
name: versionId
description: >-
One or an array of version identifiers created in COMS. This
parameter is incompatible with `s3VersionId`
schema:
oneOf:
- $ref: "#/components/schemas/VersionId"
- type: array
items:
$ref: "#/components/schemas/VersionId"
responses:
"200":
description: Returns an array of versions with matching key/value pairs.
content:
application/json:
schema:
type: array
items:
type: object
required:
- versionId
- tagset
properties:
versionId:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
tagset:
type: array
items:
$ref: "#/components/schemas/DB-TagKeyValue"
"422":
$ref: "#/components/responses/UnprocessableEntity"
default:
$ref: "#/components/responses/Error"
components:
headers:
Content-Disposition:
description: Specifies presentational information for the object
schema:
type: string
example: >-
attachment; filename=bittercherrytree.txt;
filename*=UTF-8''skwc%E2%80%99%D3%99nj%C3%AD%C5%82c.txt
Content-Length:
description: Size of the file body in bytes
schema:
type: integer
maximum: 5497558138880
example: 529
Content-Type:
description: A standard MIME type describing the format of the object data
schema:
type: string
example: text/plain; charset=utf-8
ETag:
description: >-
An entity tag (ETag) is an opaque identifier assigned by a web server to
a specific version of a resource found at a URL
schema:
type: integer
example: '"9d1aaa54b84e1d6ccc6e0477c5717fe3"'
Last-Modified:
description: Creation date of the object
schema:
type: string
format: date-time
example: Fri March 11 2022 15:42:05 GMT-0700 (Pacific Daylight Time)
Location:
description: URL Location of the moved resource
schema:
type: string
example: >-
https://your.objectstore.com/yourbucket/coms/env/00000000-0000-0000-0000-000000000000?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=credential%2F20220411%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220411T204528Z&X-Amz-Expires=300&X-Amz-Signature=SIGNATURE&X-Amz-SignedHeaders=host&x-id=GetObject
x-amz-server-side-encryption:
description: >-
If the object is stored using server-side encryption either with an AWS
KMS key or an Amazon S3-managed encryption key, the response includes
this header with the value of the server-side encryption algorithm used
when storing this object in Amazon S3 (for example, AES256, aws:kms).
schema:
type: string
example: AES256
x-amz-version-id:
description: Version of the object
schema:
type: string
example: 1649457725874
x-amz-meta-id:
description: The Object ID
schema:
type: string
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
x-amz-meta-name:
description: The original filename of the object
schema:
type: string
example: foobar.txt
parameters:
Header-ContentDisposition:
in: header
name: Content-Disposition
required: true
schema:
type: string
description: >-
A valid RFC 6266 header. Must include a type with either a
`filename` or `filename*` parameter using the encoding defined in RFC
8187 (normally UTF-8). For example, `skwc’әnjíłc.txt` must be
represented as a url-encoded string
`skwc%E2%80%99%D3%99nj%C3%AD%C5%82c.txt`.
example: >-
attachment; filename=bittercherrytree.txt;
filename*=UTF-8''skwc%E2%80%99%D3%99nj%C3%AD%C5%82c.txt
Header-ContentLength:
in: header
name: Content-Length
required: true
schema:
type: integer
description: A valid RFC 2616 header. Must be present for PUT requests.
maximum: 5497558138880
example: 3495
Header-ContentType:
in: header
name: Content-Type
schema:
type: string
description: A valid RFC 2045 MIME type
default: application/octet-stream
example: application/octet-stream
Header-Metadata:
in: header
name: x-amz-meta-*
description: >-
An arbitrary metadata key/value pair. Must contain the x-amz-meta-
prefix to be valid. Multiple metadata pairs can be defined. Keys must be
unique, contain no whitespace, and will be converted to lowercase.
schema:
type: string
minimum: 1
example:
- x-amz-meta-foo
- x-amz-meta-bar
- x-amz-meta-baz
Path-BucketId:
in: path
name: bucketId
description: Uuid of a bucket
required: true
schema:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
Path-InviteToken:
in: path
name: token
description: Uuid of an invitation token
required: true
schema:
type: string
format: uuid
example: 59aa2c57-2d3d-4e78-99fc-4886457bd8b3
Path-ObjectId:
in: path
name: objectId
description: Uuid of an object
required: true
schema:
type: string
format: uuid
example: 48a65990-2e48-46b2-94eb-7f4fe13468ea
Query-Active:
in: query
name: active
description: Boolean on active status
schema:
type: boolean
example: true
Query-BucketId:
in: query
name: bucketId
description: Uuid or array of uuids representing the bucket
schema:
oneOf:
- type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
- type: array
items:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
Query-BucketName:
in: query
name: name
description: A display name given to the bucket on creation
schema:
type: string
example: Environmental Documents
Query-BucketPerms:
in: query
name: bucketPerms
description: >-
Boolean representing whether or not to include objects from buckets with
matching permissions
schema:
type: boolean
example: true
Query-DeleteMarker:
in: query
name: deleteMarker
description: Boolean on object version DeleteMarker status
schema:
type: boolean
example: true
Query-Download:
in: query
name: download
description: >-
Download mode behavior. Default behavior (undefined) will yield an HTTP
302 redirect to the S3 bucket via presigned URL. If `proxy` is
specified, the object contents will be available proxied through COMS.
If `url` is specified, expect an HTTP 201 cotaining the presigned URL as
a JSON string in the response.
schema:
$ref: "#/components/schemas/DownloadMode"
Query-Email:
in: query
name: email
description: Search by specific email
schema:
type: string
format: email
example: bobsmith@gov.bc.ca
Query-ExpiresIn:
in: query
name: expiresIn
description: How many seconds the pre-signed URL should remain valid for
schema:
type: integer
format: int32
default: 300
example: 300
Query-FirstName:
in: query
name: firstName
description: Search by specific first name
schema:
type: string
example: bob
Query-FullName:
in: query
name: fullName
description: Search by specific full name
schema:
type: string
example: bob smith
Query-IdentityId:
in: query
name: identityId
description: >-
String or array of strings representing the user (identified by optional
KC_IDENTITYKEY env variable)
schema:
oneOf:
- type: string
example: 5dad1ec9d3c04b0f8eadcb4d9fa98987
- type: array
items:
type: string
example: 5dad1ec9d3c04b0f8eadcb4d9fa98987
Query-Idp:
in: query
name: idp
description: >-
Idp or array of idps representing the identity provider(s) (i.e. `idir`,
`bceid-basic`, etc)
schema:
oneOf:
- type: string
example: idir
- type: array
items:
type: string
example: idir
Query-Key:
in: query
name: key
description: The prefix given to objects in the bucket
schema:
type: string
example: coms/env
Query-LastName:
in: query
name: lastName
description: Search by specific last name
schema:
type: string
example: smith
Query-Latest:
in: query
name: latest
description: Boolean on object version is latest
schema:
type: boolean
example: true
Query-Limit:
in: query
name: limit
description: >-
The page size, number of objects in a page. Must specify page number
when defined.
schema:
type: number
example: 10
Query-MimeType:
in: query
name: mimeType
description: The object MIME Type
schema:
type: string
description: The object MIME Type
default: application/octet-stream
example: text/plain
Query-Name:
in: query
name: name
description: The filename of the object (typically the original filename)
schema:
type: string
example: foobar.txt
Query-ObjectId:
in: query
name: objectId
description: Uuid or array of uuids representing the object
schema:
oneOf:
- type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
- type: array
items:
type: string
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
Query-ObjectPerms:
in: query
name: objectPerms
description: >-
Boolean representing whether or not to include buckets containing
objects with matching permissions
schema:
type: boolean
example: true
Query-Order:
in: query
name: order
description: Order in ascending or descending. Default to ascending order.
schema:
type: string
enum:
- asc
- desc
example: asc
Query-Path:
in: query
name: path
description: The canonical S3 path string of the object
schema:
type: string
example: coms/env/ac246e31-c807-496c-bc93-cd8bc2f1b2b4
Query-PermCode:
in: query
name: permCode
description: The permission type
schema:
oneOf:
- $ref: "#/components/schemas/PermCode"
- type: array
items:
$ref: "#/components/schemas/PermCode"
Query-Public:
in: query
name: public
description: Boolean on public status
schema:
type: boolean
example: true
Query-Permissions:
in: query
name: permissions
description: Boolean representing whether or not to include matching permissions
schema:
type: boolean
example: true
Query-Page:
in: query
name: page
description: >-
The index of the page to return. The index of first page is 1. Must
specify limit when defined.
schema:
type: number
example: 1
Query-Sort:
in: query
name: sort
description: Any possible object Column.
schema:
type: string
enum:
- id
- path
- public
- active
- createdBy
- updatedBy
- updatedAt
- bucketId
- name
example: name
Query-S3VersionId:
in: query
name: s3VersionId
description: A specified version
schema:
$ref: "#/components/schemas/S3VersionId"
Query-TagSet:
in: query
name: tagset[*]
description: >-
Tags for the object, defined as a Key/Value tag. The query must be
formatted in deepObject style notation, where a tag-set made out of
multiple tags would be encoded something similar to
`tagset[x]=a&tagset[y]=b`. Only one value can exist for a given tag key.
schema:
$ref: "#/components/schemas/DB-TagKeyValue"
style: deepObject
explode: true
Query-UserSearch:
in: query
name: search
description: >-
General OR search across username, email and fullName. Intended for use
in freetext searches or autofilling fields.
schema:
type: string
example: smith
Query-UserId:
in: query
name: userId
description: Uuid or array of uuids representing the user
schema:
oneOf:
- type: string
format: uuid
example: 00000000-0000-0000-0000-000000000000
- type: array
items:
type: string
format: uuid
example: 00000000-0000-0000-0000-000000000000
Query-Username:
in: query
name: username
description: Search by specific username
schema:
type: string
example: bobsmith
Query-VersionId:
in: query
name: versionId
description: A specified version
schema:
$ref: "#/components/schemas/VersionId"
schemas:
DB-Bucket:
title: DB Bucket
type: object
allOf:
- type: object
required:
- accessKeyId
- active
- bucket
- bucketId
- bucketName
- endpoint
- key
- region
- secretAccessKey
properties:
accessKeyId:
type: string
description: >-
S3 account Access Key Id, similar to a username. This value will
be redacted from the API response.
example: REDACTED
active:
type: boolean
description: Determines whether this bucket is considered active in COMS
default: true
example: true
bucket:
type: string
description: The ID of a bucket
example: ezakyp
bucketName:
type: string
description: A human-readable label or title
example: Geospatial Maps
bucketId:
type: string
description: The primary identifier for this bucket
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
endpoint:
type: string
description: A valid RFC 3986 formatted S3 Service URI endpoint
maxLength: 255
example: https://my-objectstore.ca
key:
description: The prefix given to objects in the bucket
type: string
example: coms/env
maxLength: 255
lastSyncRequestedDate:
description: Time when a sync request was last submitted for the bucket
type: string
format: date-time
example: "2022-03-11T23:19:16.343Z"
default: null
region:
type: string
description: >-
The geographical zone defined by the S3 service where your
bucket is located
example: ca-central-1
secretAccessKey:
type: string
description: >-
S3 account Secret Access Key, similar to a password. This value
will be redacted from the API response.
example: REDACTED
- $ref: "#/components/schemas/DB-TimestampUserData"
DB-BucketPermission:
title: DB Bucket Permission
type: object
allOf:
- type: object
required:
- id
- bucketId
- userId
- permCode
properties:
id:
type: string
format: uuid
description: The unique identifier for this permission tuple
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
bucketId:
type: string
format: uuid
description: The unique identifier for the bucket
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
userId:
type: string
format: uuid
description: The unique identifier of the user
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
permCode:
$ref: "#/components/schemas/PermCode"
- $ref: "#/components/schemas/DB-TimestampUserData"
DB-IdentityProvider:
title: DB Identity provider
type: object
allOf:
- type: object
required:
- idp
- active
properties:
idp:
type: string
description: The identity provider string
example: idir
active:
type: boolean
description: Determines whether this identity provider is considered active
default: true
example: true
- $ref: "#/components/schemas/DB-TimestampUserData"
DB-Metadata:
title: DB Metadata
type: object
required:
- metadata
properties:
metadata:
type: object
description: User-defined metadata
example:
color: red
department: finance
DB-MetadataKeyValue:
title: DB Metadata Key Value
type: object
required:
- key
- value
properties:
key:
type: string
description: The metadata key
example: x
value:
type: string
description: The metadata value
example: a
DB-Object:
title: DB Object
type: object
allOf:
- type: object
required:
- id
- path
- public
- active
properties:
id:
type: string
description: The primary identifier for this object
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
path:
type: string
description: The canonical S3 path string of the object
example: coms/env/foobar.txt
public:
type: boolean
description: Determines whether this object is publicly accessible
default: false
example: false
active:
type: boolean
description: Determines whether this object is considered active
default: true
example: true
bucketId:
type: string
description: The primary identifier for the bucket
format: uuid
example: c05c7650-5f48-4e51-bf17-762e8fc121a1
name:
type: string
description: The filename of the original file uploaded
example: foobar.txt
lastSyncedDate:
type: string
format: date-time
description: Time when the object was last synced with the S3 bucket
example: "2022-03-11T23:19:16.343Z"
default: null
- $ref: "#/components/schemas/DB-TimestampUserData"
DB-ObjectPermission:
title: DB Object Permission
type: object
allOf:
- type: object
required:
- id
- objectId
- userId
- permCode
properties:
id:
type: string
format: uuid
description: The unique identifier for this permission tuple
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
objectId:
type: string
format: uuid
description: The unique identifier for the object
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
userId:
type: string
format: uuid
description: The unique identifier of the user
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
permCode:
$ref: "#/components/schemas/PermCode"
- $ref: "#/components/schemas/DB-TimestampUserData"
DB-TagKeyValue:
title: DB Tag Key Value
type: object
required:
- key
properties:
key:
type: string
description: The tag key
example: x
value:
type: string
description: The tag value
example: a
DB-Tags:
title: DB Tags
type: object
allOf:
- type: object
properties:
tags:
type: object
description: User-defined tags
example:
classification: Top Secret
coms-id: 989de109-1487-423b-bf82-bee38c26ee3c
priority: urgent
DB-TimestampUserData:
title: DB Timestamp User Data
type: object
required:
- createdBy
- createdAt
properties:
createdBy:
type: string
format: uuid
description: >-
The subject id of the current user if request was authenticated with
a Bearer token (ex. JWT), or a 'nil' uuid if request was
authenticated via Basic auth
example: 72cf13d7-aef7-4ad5-8ddd-0ff23eefb442
createdAt:
type: string
format: date-time
description: Time when this record was created
example: "2022-03-11T23:19:16.343Z"
updatedBy:
type: string
format: uuid
description: >-
The subject id of the current user if request was authenticated with
a Bearer token (ex. JWT), or a 'nil' uuid if request was
authenticated via Basic auth
default: null
example: 72cf13d7-aef7-4ad5-8ddd-0ff23eefb442
updatedAt:
type: string
format: date-time
description: Time when this record was last updated
example: "2022-03-11T23:19:16.343Z"
DB-User:
title: DB User
type: object
allOf:
- type: object
properties:
userId:
type: string
description: Subject id of the user (Usually the sub claim in a JWT)
example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
identityId:
type: string
description: >-
Identity id of the user (Usually the sub claim in a JWT but can
be redefined to a different claim with the `KC_IDENTITYKEY` env
variable)
example: 5dad1ec9d3c04b0f8eadcb4d9fa98987
idp:
type: string
description: Identity provider used by the OIDC server
example: idir
email:
type: string
description: Registered email for this user
example: jsmith@gov.bc.ca
username:
type: string
description: Username of this user
example: jsmith
firstName:
type: string
description: First name of this user
example: Jane
lastName:
type: string
description: Last name of this user
example: Smith
active:
type: boolean
description: Determines whether this user is considered active
default: true
example: true
- $ref: "#/components/schemas/DB-TimestampUserData"
DB-Version:
title: DB Version
type: object
allOf:
- type: object
required:
- id
- s3VersionId
- objectId
- mimeType
- deleteMarker
properties:
id:
type: string
description: The primary identifier for this version
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
s3VersionId:
type: string
description: a version identifier created in S3
example: "1647462569641"
objectId:
type: string
description: The primary identifier for the parent object
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
mimeType:
type: string
description: The MIME Type of the version
default: application/octet-stream
example: text/plain
deleteMarker:
type: boolean
description: Whether or not this version is a S3 delete-marker
example: false
etag:
type: integer
description: >-
An entity tag (ETag) is an opaque identifier assigned by a web
server to a specific version of a resource found at a URL
example: '"9d1aaa54b84e1d6ccc6e0477c5717fe3"'
lastModifiedDate:
type: string
format: date-time
description: >-
The object creation date or the last modified date (as exposed
by S3's `Last-Modified` header), whichever is the latest.
example: "2022-03-11T23:19:16.343Z"
default: null
- $ref: "#/components/schemas/DB-TimestampUserData"
DownloadMode:
title: Download Mode
type: string
description: Download mode behavior overrides
enum:
- proxy
- url
example: proxy
PermCode:
title: Permission Code
type: string
description: Permission code/type
enum:
- CREATE
- READ
- UPDATE
- DELETE
- MANAGE
example: UPDATE
Request-CreateBucket:
title: Request Create Bucket
type: object
required:
- accessKeyId
- bucket
- bucketName
- endpoint
- secretAccessKey
allOf:
- $ref: "#/components/schemas/Request-UpdateBucket"
- type: object
properties:
key:
description: >-
The prefix given to objects in the bucket. Defaults to "/" if
undefined.
type: string
default: /
example: coms/env
permCodes:
type: array
items:
type: string
description: >-
Optional array of permCodes for each permission being given to the current user.
Accepts any of `"READ", "CREATE", "UPDATE", "DELETE", "MANAGE"`.
Defaults to all permCodes if unspecified.
example: ["READ", "CREATE", "UPDATE"]
Request-CreateBucketChild:
title: Request Create Bucket Child
type: object
required:
- bucketName
- subKey
allOf:
- type: object
properties:
bucketName:
type: string
description: A human-readable label or title
maxLength: 255
example: Geospatial Maps
subKey:
type: string
description: a path relative to the parent bucket to the 'directory' you are mounting
maxLength: 255
example: canada/bc/maps
Request-CreateInvite:
title: Request Create Invite
type: object
properties:
bucketId:
type: string
description: >-
Optional uuid representing the bucket. Either `bucketId` or
`objectId` must be specified.
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
email:
type: string
description: >-
Optional email address of the intended recipient for this
invitation. The invitation will perform extra validation if
specified.
format: email
example: bobsmith@gov.bc.ca
expiresAt:
type: integer
description: >-
Optional desired unix epoch time for when this invitation should
expire. Defaults to 24 hours from now if unspecified. Maximum of 30 days from now.
example: 1710000000
objectId:
type: string
description: >-
Optional uuid representing the object. Either `bucketId` or
`objectId` must be specified.
format: uuid
example: 48a65990-2e48-46b2-94eb-7f4fe13468ea
permCodes:
title: Permission Code
type: array
items:
type: string
description: Optional array of permCode. Defaults to 'READ', if unspecified. Accepts any of `"READ", "CREATE", "UPDATE"` for bucket or `"READ", "UPDATE"` for objects
example: ["READ", "CREATE", "UPDATE"]
Request-UpdateBucket:
title: Request Update Bucket
type: object
properties:
accessKeyId:
type: string
description: >-
S3 account Access Key Id, similar to a username. This value will be
redacted from the API response.
example: REDACTED
active:
type: boolean
description: Whether this bucket is considered active in COMS
default: true
example: true
bucket:
type: string
description: The ID of a bucket
example: ezakyp
bucketName:
type: string
description: A human-readable label or title
example: Geospatial Maps
endpoint:
type: string
description: A valid RFC 3986 formatted S3 Service URI endpoint
maxLength: 255
example: https://my-objectstore.ca
region:
type: string
description: >-
The geographical zone defined by the S3 service where your bucket is
located
example: ca-central-1
secretAccessKey:
type: string
description: >-
S3 account Secret Access Key, similar to a password. This value will
be redacted from the API response.
example: REDACTED
Request-PermissionTuple:
title: Response Permission Tuple
type: object
required:
- userId
- permCode
properties:
permCode:
$ref: "#/components/schemas/PermCode"
userId:
type: string
description: The primary identifier for a user
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
Response-BadRequest:
title: Response Bad Request
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 400
title:
example: Bad Request
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
Response-BucketPerms:
title: Response Buckets with bucket-level permissions
type: object
properties:
bucketId:
type: string
format: uuid
description: >-
The unique identifier for the bucket. When `objectPerms=false` only
buckets with bucket-level permissions are returned.
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
permissions:
type: array
items:
$ref: "#/components/schemas/DB-BucketPermission"
Response-BucketPermsWithObject:
title: Response Buckets containing objects with object-level permissions
description: >-
When `objectPerms=true` response will include buckets containing objects
with matching permissions.
type: object
properties:
bucketId:
type: string
format: uuid
description: >-
The unique identifier for the bucket. When `objectPerms=true`
response will include buckets containing objects with matching
permissions.
example: bf246e31-c807-496c-bc93-cd8bc2f1897f
permissions:
type: array
items:
type: object
description: Array will be empty.
example: []
Response-Conflict:
title: Response Conflict
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 409
title:
example: Conflict
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409
Response-ContentTooLarge:
title: Response Content Too Large
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 413
title:
example: Content Too Large
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413
Response-Error:
title: Response Error
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 500
title:
example: Internal Server Error
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
Response-Forbidden:
title: Response Forbidden
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
title:
example: Forbidden
status:
example: 403
detail:
example: User lacks permission to complete this action
Response-Gone:
title: Response Gone
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 410
title:
example: Gone
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410
Response-InviteResult:
title: Response Invite Result
description: >-
An object containing the resource uuid and the type of resource it
represents.
type: object
required:
- resource
- type
properties:
resource:
type: string
format: uuid
description: The unique identifier for the resource.
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
type:
type: string
description: The type of resource the uuid represents
enum:
- bucketId
- objectId
example: objectId
Response-LengthRequired:
title: Length Required
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 411
title:
example: Length Required
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/411
Response-NotFound:
title: Response Not Found
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 404
title:
example: Not Found
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
Response-NotImplemented:
title: Response Not Implemented
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 501
title:
example: This action is not supported in the current authentication mode
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501
Response-ObjectDeleted:
title: Response Object Deleted
type: object
properties:
$metadata:
$ref: "#/components/schemas/S3-Metadata"
DeleteMarker:
type: boolean
example: true
s3VersionId:
type: string
description: A version identifier created in S3
example: "1647462569641"
Response-ObjectDetails:
title: Response Object Details
type: object
allOf:
- $ref: "#/components/schemas/DB-Object"
- type: object
required:
- length
- mimeType
- Key
- Location
properties:
length:
type: integer
description: Size of the file body in bytes
maximum: 5497558138880
example: 529
mimeType:
type: string
description: The object MIME Type
default: application/octet-stream
example: text/plain
versionId:
type: string
description: The primary identifier for this version in the COMS database
format: uuid
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
- $ref: "#/components/schemas/DB-Metadata"
- $ref: "#/components/schemas/DB-Tags"
- $ref: "#/components/schemas/S3-Object"
Response-ObjectPerms:
title: Response Objects with object-level permissions
type: object
properties:
objectId:
type: string
format: uuid
description: >-
The unique identifier for the object. When `bucketPerms=false` only
objects with matching object-level permissions are returned.
example: ac246e31-c807-496c-bc93-cd8bc2f1b2b4
permissions:
type: array
items:
$ref: "#/components/schemas/DB-ObjectPermission"
Response-ObjectPermsWithBucket:
title: Response Objects in buckets with bucket-level permissions
description: >-
When `objectPerms=true` response will include objects in buckets with
matching permissions.
type: object
properties:
objectId:
type: string
format: uuid
description: >-
The unique identifier for the object. When `bucketPerms=true`
response will include objects in buckets with matching permissions.
example: bf246e31-c807-496c-bc93-cd8bc2f1897hf
permissions:
type: array
items:
type: object
description: Array will be empty.
example: []
Response-PresignedURL:
title: Response Presigned URL
type: string
description: A Presigned S3 URL
example: >-
https://your.objectstore.com/yourbucket/coms/env/00000000-0000-0000-0000-000000000000?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=credential%2F20220411%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220411T204528Z&X-Amz-Expires=300&X-Amz-Signature=SIGNATURE&X-Amz-SignedHeaders=host&x-id=GetObject
Response-Problem:
title: Response Problem
type: object
required:
- type
- title
- status
properties:
type:
type: string
description: What type of problem, link to explanation of problem
title:
type: string
description: Title of problem, generally the HTTP Status Code description
status:
type: string
description: The HTTP Status code
detail:
type: string
description: >-
A short, human-readable explanation specific to this occurrence of
the problem
instance:
type: string
description: >-
A URI reference that identifies the specific occurrence of the
problem
Response-Unauthorized:
title: Response Unauthorized
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
title:
example: Unauthorized
status:
example: 401
detail:
example: Invalid authorization credentials
Response-UnsupportedMediaType:
title: Unsupported Media Type
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
properties:
status:
example: 415
title:
example: Unsupported Media Type
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/415
Response-ValidationError:
title: Response Validation Error
type: object
allOf:
- $ref: "#/components/schemas/Response-Problem"
- type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- message
properties:
value:
type: object
description: Contents of the field that was in error.
example: {}
message:
type: string
description: The error message for the field.
example: Invalid value `encoding`.
status:
example: 422
title:
example: Unprocessable Entity
type:
example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422
Response-VersionDeleted:
title: Response Version Deleted
type: object
properties:
$metadata:
$ref: "#/components/schemas/S3-Metadata"
s3VersionId:
type: string
description: a version identifier created in S3
example: "1647462569641"
S3-Metadata:
title: S3 Metadata
type: object
required:
- httpStatusCode
- extendedRequestId
properties:
httpStatusCode:
type: integer
description: S3 Endpoint internal HTTP code
example: 200
extendedRequestId:
type: string
description: S3 Endpoint unique internal request id
example: a0ec1be0a99a08aee6026ba9756da40327f2d3ce844499b7ee752082f3fb22e3
attempts:
type: integer
description: Number of attempts performed by S3
example: 1
totalRetryDelay:
type: integer
description: S3 delay for retries
example: 0
S3-Object:
title: S3 Object
type: object
required:
- $metadata
- ETag
properties:
$metadata:
$ref: "#/components/schemas/S3-Metadata"
ETag:
type: string
description: S3 Identifier for a specific version of this object
example: '"9d1aaa54b84e1d6ccc6e0477c5717fe3"'
Bucket:
type: string
description: S3 Identifier for the bucket
example: ezakyp
Key:
type: string
description: Key of the object
example: coms/env/00000000-0000-0000-0000-000000000000
Location:
type: string
description: URL to the resource just uploaded
example: >-
https://your.objectstore.com/yourbucket/coms/env/00000000-0000-0000-0000-000000000000
ServerSideEncryption:
type: string
description: >-
If the object is stored using server-side encryption either with an
AWS KMS key or an Amazon S3-managed encryption key, this field
specifies the server-side encryption algorithm used when storing
this object in Amazon S3 (for example, AES256, aws:kms).
example: AES256
s3VersionId:
type: string
description: A version identifier created in S3
example: "1647462569641"
S3-Version:
title: S3 Version
type: object
required:
- ETag
- Size
- StorageClass
- s3VersionId
- IsLatest
- LastModified
properties:
ETag:
type: string
description: S3 Identifier for a specific version of this object
example: 9d1aaa54b84e1d6ccc6e0477c5717fe3
Size:
type: integer
description: Size of the object in bytes
example: 529
StorageClass:
description: >-
S3 storage classes based on the data access, resiliency, and cost
requirements of your workloads
example: STANDARD
key:
description: Key of the object
s3VersionId:
type: string
description: A version identifier created in S3
example: "1647462569641"
IsLatest:
description: >-
Specifies whether the object is (true) or is not (false) the latest
version of an object.
LastModified:
type: string
format: date-time
example: "2022-03-11T23:19:16.343Z"
Owner:
$ref: "#/components/schemas/S3-VersionOwner"
S3-VersionList:
title: S3 Version List
type: object
required:
- $metadata
- IsTruncated
- MaxKeys
- Name
- Prefix
- Versions
properties:
$metadata:
$ref: "#/components/schemas/S3-Metadata"
IsTruncated:
type: boolean
description: Whether or not this object listing is complete
example: false
KeyMarker:
type: string
description: Marks the last key returned in a truncated response
example: ""
MaxKeys:
type: integer
format: int32
description: >-
Sets the maximum number of keys returned in the response. By default
the action returns up to 1,000 key names. The response might contain
fewer keys but will never contain more.
example: 1000
Name:
type: string
description: Name of the S3 bucket
Prefix:
type: string
description: Keys that begin with the indicated prefix
example: coms/env/ac246e31-c807-496c-bc93-cd8bc2f1b2b4
VersionIdMarker:
type: string
description: Marks the last version of the key returned in a truncated response
example: ""
Versions:
type: array
items:
$ref: "#/components/schemas/S3-Version"
S3-VersionOwner:
title: S3 Version Owner
type: object
required:
- DisplayName
- ID
properties:
DisplayName:
type: string
description: The bucket accessKeyId/owner
example: abcdef
ID:
type: string
description: The bucket accessKeyId/owner
example: abcdef
S3VersionId:
title: S3 Version ID
type: string
description: >-
A version identifier created in S3. This parameter is incompatible with
`versionId`
maximum: 1024
example: "1647462569641"
VersionId:
title: Version ID
type: string
description: >-
A version identifier created by COMS. This parameter is incompatible
with `s3VersionId`
format: uuid
example: c05c7650-5f48-4e51-bf17-762e8fc121a1
responses:
AddedQueueLength:
description: Returns the number of objects that have been added to the queue
content:
text/plain:
schema:
type: integer
example: 5
description: Number of objects added to the queue
Accepted:
description: Accepted
BadRequest:
description: Bad Request (Request is missing content or malformed)
content:
application/json:
schema:
$ref: "#/components/schemas/Response-BadRequest"
Conflict:
description: Conflict (Request conflicts with server state)
content:
application/json:
schema:
$ref: "#/components/schemas/Response-Conflict"
ContentTooLarge:
description: Content Too Large
content:
application/json:
schema:
$ref: "#/components/schemas/Response-ContentTooLarge"
Error:
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Response-Error"
Found:
description: Resource requested has been temporarily moved
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/Response-Forbidden"
Gone:
description: Gone
content:
application/json:
schema:
$ref: "#/components/schemas/Response-Gone"
LengthRequired:
description: Length Required
content:
application/json:
schema:
$ref: "#/components/schemas/Response-LengthRequired"
NoContent:
description: No Content
NotFound:
description: Not Found
content:
application/json:
schema:
$ref: "#/components/schemas/Response-NotFound"
NotImplemented:
description: >-
The server does not support the functionality required to fulfill the
request.
content:
application/json:
schema:
$ref: "#/components/schemas/Response-NotImplemented"
NotModified:
description: Not Modified
S3Found:
description: Returns a temporary pre-signed S3 object URL location header
headers:
Location:
$ref: "#/components/headers/Location"
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Response-Unauthorized"
UnprocessableEntity:
description: Unprocessable Content (Generally validation error(s))
content:
application/json:
schema:
$ref: "#/components/schemas/Response-ValidationError"
UnsupportedMediaType:
description: Unsupported Media Type
content:
application/json:
schema:
$ref: "#/components/schemas/Response-UnsupportedMediaType"
securitySchemes:
BasicAuth:
type: http
description: Basic auth via environment defined username and password
scheme: basic
BearerAuth:
type: http
description: Bearer token auth using an OIDC issued JWT token
scheme: bearer
bearerFormat: JWT
OpenID:
type: openIdConnect
description: OpenID Connect endpoint for acquiring JWT tokens
openIdConnectUrl: >-
https://logonproxy.gov.bc.ca/auth/realms/your-realm-name/.well-known/openid-configuration