Skip to main content

Using the Context API

Overview​

This document provides a step-by-step guide for uploading a file, processing it, and retrieving the results using the API. Mock data is used for demonstration purposes.

Prerequisites​

To use the API, you will need the following:

  1. API endpoint for the file upload and processing service.
  2. Any required authentication tokens or credentials (if applicable).

Steps to Use the API​

There are 4 sequential steps to upload a file, process it, and retrieve the results.

1. Request a Presigned URL for File Upload​

Description​

To upload a file, you first need to request a presigned URL from the API. This URL allows secure file uploads to the storage bucket without requiring direct access credentials. The objectKey returned in the response uniquely identifies the file in the storage bucket.

Request​

Send a GET request to the API endpoint for generating a presigned URL. The desired content type (e.g., image/jpeg) should be specified as a query parameter.

{
  "method": "GET",
  "url": "api/files/upload/presigned-url?contentType=image%2Fjpeg",
  "headers": {
    "accept": "application/json"
  },
  "body": "No body"
}

Response​

The API will return a presigned URL and an objectKey. The presignedUrl is used to upload the file, and the objectKey is used for subsequent processing.

{
  "status": 200,
  "statusText": "OK",
  "body": {
    "presignedUrl": "https://mock-bucket.s3.amazonaws.com/contents/mock-file-id.jpeg?mock-query-params",
    "objectKey": "contents/mock-file-id.jpeg"
  }
}

2. Upload the File​

Description​

Once you have the presigned URL, you can upload the file to the storage bucket. The file must be sent as binary data in the request body.

Preparing Binary Data​

To prepare the binary data for the file:

  1. Read the file from your local system using a programming language or tool of your choice.
  2. Ensure the file is sent as raw binary data in the request body.

For example, in JavaScript:

const fs = require('fs');
const binaryData = fs.readFileSync('path/to/image.jpeg');

Request​

Send a PUT request to the presignedUrl with the binary data in the body.

{
  "method": "PUT",
  "url": "https://mock-bucket.s3.amazonaws.com/contents/mock-file-id.jpeg?mock-query-params",
  "headers": {
    "Accept": "*/*",
    "Content-Type": "image/jpeg"
  },
  "body": "Binary file data"
}

Response​

The file upload will return a success response.

{
  "status": 200,
  "statusText": "OK",
  "headers": {
    "etag": "\"mock-etag\"",
    "x-amz-server-side-encryption": "AES256",
    "content-length": "0",
    "server": "AmazonS3"
  },
  "body": ""
}

3. Request Processing of the Uploaded File​

Description​

After uploading the file, you can request the API to process it. The objectKey from the presigned URL response is used to identify the file, and the desired processing actions (e.g., image-description) are specified in the request body.

Request​

Send a POST request to the processing endpoint with the objectKey and actions.

{
  "method": "POST",
  "url": "api/content/process",
  "headers": {
    "Content-Type": "application/json",
    "accept": "application/json"
  },
  "body": {
    "objectKeys": [
      "contents/mock-file-id.jpeg"
    ],
    "actions": [
      "image-description"
    ],
    "contentType": "application/json",
    "maxWordCount": 200
  }
}

Response​

The API will return a processing ID that you can use to retrieve the results.

{
  "status": 200,
  "statusText": "OK",
  "body": "mock-processing-id"
}

4. Retrieve Processing Results​

Description​

To retrieve the results of the processing, you need to construct the results URL using the processing ID returned in the previous step. The URL format is as follows:

api/content/process/{processing-id}/results

Replace {processing-id} with the actual processing ID.

Request​

Send a GET request to the constructed URL to retrieve the results.

{
  "method": "GET",
  "url": "api/content/process/mock-processing-id/results",
  "headers": {
    "accept": "*/*"
  },
  "body": "No body"
}

Response​

The API will return the processed data.

{
  "status": 200,
  "statusText": "OK",
  "body": {
    "id": "mock-processing-id",
    "timestamp": "2025-04-04T08:01:56.000Z",
    "results": [
      {
        "objectKey": "contents/mock-file-id.jpeg",
        "imageDescription": {
          "isSuccess": true,
          "result": "The image shows a mock description of the content.",
          "error": null
        }
      }
    ]
  }
}

Summary​

This walkthrough demonstrates how you can:

  1. Request a presigned URL for file upload.
  2. Upload a file using the presigned URL.
  3. Request processing of the uploaded file.
  4. Retrieve the results of the processing.

Mock data has been used to replace actual values for demonstration purposes.