Endpoint Notes

Endpoint Notes

This page outlines the general usage patterns and organization of the COMS API and is mainly intended for a technical audience, and for people who are planning on implementing and leveraging the API endpoints.

Table of Contents

• Object
  • Metadata
  • Tag
• Permission
• User

Object

Operations directly influencing an S3 Object. Certain operations not available without a database.

Object operation endpoints directly influence and manipulate S3 objects and information inherent to them. These set of endpoints serve as the main core of COMS, focusing on CRUD operations for the objects themselves.

• CREATE /object and POST /object/{objId} accept files with a multipart/form-data body. For the create endpoint, you can specify any arbitrary number of custom-named, unique form keys for each file you want to upload; each file will be uploaded and receive their own object identifier upon completion. (You do not need to use the fieldname "anyKey" - that's just an example!).
• GET /object/{objId} is to be used the most as this is the main endpoint for users to directly accessing and downloading objects.
• HEAD /object/{objId} should be used for situations where you need to get information about the object, but do not want the binary stream of the object itself.
• DELETE /object/{objId} deletes either the object or a specific version of the object. COMS follows the S3 standard for deleting versioned objects
  • If versioning is enabled, calling /object/{objId} is a soft-delete, adding a 'delete-marker' version. To restore this object, remove the delete-marker with /object/{objectId}?versionId={VersionId of delete-marker}. To hard-delete a versioned object, you must delete the last version /object/{objectId}?versionId={last version}.
  • calling in the Delete endpoint on a bucket without versioning is a hard-delete.
• The GET /object search and PATCH /object/{objId}/public public toggle require a backing database in order to function.

Metadata

Operations for managing Metadata belonging to an S3 Object.

Metadata operation endpoints directly focus on the manipulation of metadata of S3 Objects. Each endpoint will create a copy of the object with the modified metadata attached.

More details found here: Metadata and Tags

Tag

Operations for managing Tags belonging to an S3 Object.

Tag operation endpoints directly focus on the manipulation of tags of S3 Objects. Unlike Metadata, Tags can be modified without the need to create new versions of the object.

More details found here: Metadata and Tags

Permission

Operations for managing User Access Control to S3 Objects. Not available without a database.

Permission operation endpoints directly focus on associating users to objects with specific permissions. All of these endpoints require a database to function. Existing permissions can be searched for using GET /permission, and standard create, read and delete operations for permissions exist to allow users to modify access control for specific objects they have management permissions over.

More details found here: Permissions

User

Operations to list valid queryable users and identity providers. Not available without a database.

User operation endpoints focus on exposing known tracked users and identity providers. All of these endpoints require a database to function. These endpoints serve as a reference point for finding the right user and identity to manipulate in the Permission endpoints. As COMS is relatively agnostic to how a user logs in (it only cares that you exist), the onus of determining which identity provider a user uses falls onto the line of business to handle, should that be something that needs monitoring.