API Conventions

API Conventions

There are a number of conventions used in the Tendocs APIs which developers should consider when building their integrations, these are described below.

Configuration

All APIs include a "Configuration" object, within this object is a "Keys" parameter. This is for use in preview or advanced functionality, and only included under the direction of the Tendocs support team.

Required Properties

The required properties on each request are listed above the API documentation below. These must be passed with every request, all other properties are optional, or have smart defaults.

Working with Files

Files are sent in requests encoded using Base64, and returned by the API as an binary stream.

Request: File Object

The "file" object represents a file to be uploaded or processed by the API. It is sent within a JSON body, and contains the following properties:

• $content-type (string, required): The MIME type of the file. This parameter specifies the type of data contained within the file. The value should be a valid MIME type string, (see the Supported MIME Types below).

• $content (string, required): The file content encoded using Base64. This parameter contains the actual file data in a Base64-encoded format. The encoded content should be a valid Base64 string representing the file content.

Example

Here's an example request demonstrating the usage of the "File" object parameter:

{
  "file": {
    "$content-type": "image/jpeg",
    "$content": "SGVsbG8gV29ybGQhCg=="
  }
}

About Base64 Encoding

Base64 encoding is a common binary-to-text encoding scheme that converts binary data (Office Documents, images, etc) into a set of text characters from a limited character set. It is commonly used for encoding binary data, such as images or files, into a format that can be easily transmitted over text-based protocols like JSON over HTTP.

The functionality required to do this is built into most modern programming languages, with samples easily found online.

• Base64 Encoding in Java: java.util.Base64

• Base64 Encoding in C#: System.Convert.ToBase64String

Supported MIME Types:

The following MIME Types, corresponding to Office documents are supported by Tendocs APIs and can be used in the "$content-type" parameter of a File object:

• DOCX = application/vnd.openxmlformats-officedocument.wordprocessingml.document

• XSLX = application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

• PPTX = application/vnd.openxmlformats-officedocument.presentationml.presentation

Response: File

The response from Tendocs APIs are provided directly in a Binary format, using the MIME Type "application/octet-stream".

About application/octet-stream

The MIME type "application/octet-stream" is a binary file format often used to represent arbitrary binary data. It signifies that the content of the file is not associated with any specific application or file format. The term "octet" refers to a sequence of eight bits, which is commonly used to represent binary data.

Working with Binary responses (Postman and other HTTP Clients)

In Postman, you can work with API responses of the "application/octet-stream" MIME type by following these steps:

• Send a request to the API endpoint using the appropriate HTTP method (e.g., GET, POST).

• When you receive the response, click on the "Body" tab in the Postman interface.

• In the "Body" section, you will see different options for handling the response. To work with the "application/octet-stream" data, select the "Save response" option.

• Choose the desired location on your local machine to save the response as a raw binary file, providing it with the extension you know the file to be (.XSLX/.DOCX/.PPTX/.PDF).

By saving the response as a raw file, you can then access and work with it using the associated Office or PDF application.

Working with Binary responses (Code)

Most modern programming languages have the functionality necessary to easily work with a binary response. Here are some examples:

C#

In C#, you can use the HttpClient class to make the HTTP request and handle the "application/octet-stream" response. Here's an example:

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        using (HttpClient client = new HttpClient())
        {
            HttpResponseMessage response = await client.GetAsync("https://example.com/api/endpoint");
            response.EnsureSuccessStatusCode();

            using (var fileStream = System.IO.File.Create("response_data.bin"))
            {
                await response.Content.CopyToAsync(fileStream);
                fileStream.Flush();
            }
        }
    }
}

Python

To work with "application/octet-stream" responses in Python, you can use libraries such as requests or urllib to make the HTTP request and handle the response. Once you obtain the response content, you can save it as a binary file. Here's an example using the requests library:

import requests
response = requests.get(url, headers=headers)
with open('response_data.bin', 'wb') as file:
    file.write(response.content)

Java

In Java, you can use the java.net.HttpURLConnection class to make the HTTP request and retrieve the "application/octet-stream" response. You can then save the response content to a file. Here's an example:

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class Main {
    public static void main(String[] args) throws IOException {
        URL url = new URL("https://example.com/api/endpoint");
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod("GET");

        int responseCode = connection.getResponseCode();
        if (responseCode == HttpURLConnection.HTTP_OK) {
            try (InputStream inputStream = connection.getInputStream();
                 FileOutputStream outputStream = new FileOutputStream("response_data.bin")) {
                byte[] buffer = new byte[4096];
                int bytesRead;
                while ((bytesRead = inputStream.read(buffer)) != -1) {
                    outputStream.write(buffer, 0, bytesRead);
                }
            }
        }

        connection.disconnect();
    }
}