Skip to main content

Creating a document in Embrace

In order to add a file to a collection within Embrace, you need to upload the file to the storage service and then create a document in the Embrace system. This guide will walk you through the process of uploading a document to Embrace.

  1. Initiate Upload
  2. Upload data to storage
  3. Create Document

Initiate Upload

Using an API client, initiate the document upload process by sending a POST request, the POST body should contain contentLength and contentType for the file, to /documents/upload endpoint. This request will return a presigned URL that you can use to upload the document directly to the storage service.

Upload data to storage

The presigned URL from the /documents/upload POST response enables uploading of a file directly to an S3 bucket with the necessary authentication and authorization included in the URL itself. PUT requests do not require multipart form data and instead upload the file content as the request body.

Presigned URL Format

A presigned S3 URL typically looks like this:

https://<bucket-name>.s3.<region>.amazonaws.com/<key>?<query-parameters>

Key components:

  • Bucket Name: The name of the S3 bucket.
  • Key: The path to the file within the bucket.
  • Query Parameters: Authentication and configuration information, such as X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, and X-Amz-Signature.

Steps to Create a PUT Request

  1. Extract the Presigned URL from /documents/upload response
  • Use the full presigned URL as the target for the PUT request.
  1. Set the Required Headers
  • If specified in the presigned URL or accompanying instructions, include headers such as Content-Type or x-amz-server-side-encryption.
  1. Prepare the Request Body
  • The file content itself is the body of the PUT request. Load the content from a string, buffer, or disk file.
  1. Send the PUT Request
  • Use an HTTP client to send the request, placing the file content in the body of the PUT request.

Example PUT Request Construction

Below is a generic example:

  • Presigned URL:
https://example-bucket.s3.us-west-2.amazonaws.com/path/to/object?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Signature=...
  • Create PUT Request:
  1. Set Headers:
  Content-Length: 1024
Content-Type: text/plain
x-amz-server-side-encryption: AES256
  1. Set Request Body:
<file content here>
  1. Example:
  curl -X PUT \
-H "Content-Length: 1024" \
-H "Content-Type: text/plain" \
-H "x-amz-server-side-encryption: AES256" \
--data-binary @/path/to/file.txt \
"https://example-bucket.s3.us-west-2.amazonaws.com/path/to/object?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Date=...&X-Amz-Signature=..."

Implementation Notes

  • Request Body: The file content itself is the body of the PUT request. The sender is required to implement loading the content from a string, buffer, or disk file into the request body.
  • Headers: Ensure any required headers, such as Content-Type or encryption options, are included in the request.

Additional Considerations

  • Presigned URL Expiry: Ensure the presigned URL is valid before making the PUT request, the presigned URL expires after 5 minutes.
  • Content Type: Include the appropriate Content-Type.
  • Content Length: Include the size of the Content in bytes.

Create Document

After successfully uploading the document, create a document by sending a POST request to the /documents endpoint. The POST body should contain the url of the uploaded document, name, and collectionIds for the document.


Document Creation Sequence Diagram