Data File Upload API

This API endpoint is intended to be used to upload large files/artifacts for processing within the Opsera backend workflow.

Overview

The File Upload API enables secure transmission of structured data files to our platform. It supports various file formats including JSON, CSV, XML, and YAML in both raw and compressed (gzip) formats. This API is designed for data migration and integration, providing an efficient pathway for transferring data into our system.

API Endpoint

POST https://api.[opsera-org].opsera.io/data-migration-file/data/upload

Opsera API Token Generation

From within the Opsera portal, follow these steps to generate an API token if you don't already have one.

Login to the Opsera portal.
Access User Profile: Click on your user avatar or profile picture at the top-right corner of the dashboard.
Navigate to API Tokens: Select "API Tokens" or "Personal Access Tokens" from the profile settings menu.
Create a New API Token: Click on the "Create New Token" button and provide a name for the token.
Define Permissions: Choose the appropriate permissions or scopes for the token.
Generate and Save the Token: Click "Generate Token" and securely store the displayed token.

For more information please see: Personal Access Tokens | Opsera Next Gen DevOps Platform : End User Documentation

Authentication

All requests require authentication using a bearer token.

Obtain an API token from the Opsera portal
Include the token in the Authorization header
Authorization: Bearer <your_token>

Required Headers

Header	Description	Required	Example

Header	Description	Required	Example
`Authorization`	Bearer token for authentication	Yes	`Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
`Content-Type`	Media type of the file being uploaded	Yes	`application/json`
`X-File-Content-Length`	Size of the file in bytes	Yes	`42768`
`X-File-Content-MD5`	MD5 hash of the file for integrity verification	Yes	`d41d8cd98f00b204e9800998ecf8427e`
`X-File-Name`	Name of the file being uploaded	Yes	`project_data.json`
`X-File-Content-Classification`	Classification category for the uploaded content	Yes	`Insights.UnityProjects`
`Content-Encoding`	Encoding of the file content (for compressed files)	Only for compressed files	`gzip`

Content Classification

The X-File-Content-Classification header specifies the category of data being uploaded. Please contact your Opsera account representative for the appropriate classification value for your use case.

Supported File Types

File Type	Content-Type Header

File Type	Content-Type Header
JSON	`application/json`
CSV	`text/csv` or `application/csv`
XML	`text/xml` or `application/xml`
YAML	`application/yaml` or `application/x-yaml`
Gzipped JSON	`application/json` with `Content-Encoding: gzip`
Gzipped CSV	`text/csv` with `Content-Encoding: gzip`
Gzipped XML	`application/xml` with `Content-Encoding: gzip`
Gzipped YAML	`application/yaml` with `Content-Encoding: gzip`

Request Body

The request body should contain the raw file content as binary data.

File Validation

The API performs the following validations:

The content type is checked against supported formats
The file size is validated against the provided X-File-Content-Length
The MD5 hash is verified against the provided X-File-Content-MD5
The file content is validated for correctness based on the content type

Response

A successful upload will return a 200 OK response with the following JSON structure:

{   
  "id": "artifactId",   
  "contentLength": 42768,   
  "contentMD5": "d41d8cd98f00b204e9800998ecf8427e" 
}

Description of Response Attributes

id: A string representing the unique identifier (artifactId) assigned to the uploaded file. This ID can be used for future references or operations related to this file.
contentLength: A number indicating the size of the original (uncompressed) file in bytes. This should match the value you provided in the X-File-Content-Length header.
contentMD5: A string containing the MD5 hash of the original (uncompressed) file. This should match the value you provided in the X-File-Content-MD5 header.

Error Codes

Status	Description

Status	Description
200	Successful upload
400	Bad request - invalid content type, content length, MD5, or payload
403	Forbidden - invalid authentication
500	Server error

Examples

Uploading a JSON File

Uploading a CSV File

Uploading a Compressed JSON File

Uploading a Compressed CSV File

Important Notes for All Uploads

The X-File-Content-Length header should represent the size in bytes of the original file content
The X-File-Content-MD5 should be the MD5 hash of the original file content
For compressed files, these values should represent the uncompressed data

Important Notes for Compressed Files

When uploading compressed files:

The Content-Type header should reflect the type of the uncompressed content (e.g., application/json for a gzipped JSON file)
Always include the Content-Encoding: gzip header
X-File-Content-Length should be the size of the original uncompressed file
X-File-Content-MD5 should be the MD5 hash of the original uncompressed content

Sample Code

Node.js Example

Getting Help

If you encounter any issues not covered in this documentation, please contact our support team or open a ticket in the customer support portal.

Opsera Engagement