Binary Data

API Express uses JSON format so the Base64 format is used to work with binary data (follow this link to learn more).

For testing, you can use Base64 Converter to convert ordinary strings to strings in Base64 format and vise versa.

API Express provides two types of services: Generated and Custom.

Binary data in Generated Services

API Express provides embedded support of Binary for Generated services.

1. Fields with type BLOB in Generated services are considered as Binary.
2. Operations GET and LIST will convert the value of this field into a Base64 String.
3. Operations CREATE and UPDATE will accept String in Base64 format and API Express will save the converted binary into a database.

Binary data in Custom Services

Binary in custom flow is available for the following cases:

1. Component START can accept binary when HTTP type is POST, PUT or PATCH and field type in REQUEST BODY is Binary. Binary value becomes available in flow as Binary Request
2. Component REST can return binary response when Is binary check box is enabled in RESPONSE BODY section. Binary value becomes available in flow as Binary Response
3. Component REST can accept binary when the HTTP type is set to POST, PUT or PATCH and the Type is Binary in the REQUEST BODY section; also, field Binary Body should be mapped on Binary Request or Binary Response
4. Component END can return binary response when check box Is binary is selected in RESPONSE BODY section and value of Binary Body combobox is Binary request or Binary response

To better understand how it works let’s consider an example:

Example 1. Binary in Generated services

Relational database has table files with columns id, name, and content:
id - unique identifier of files
name - file name
content - file binary content

The following DDL scripts can be used for

CREATE TABLE files
(
 id      INT          NOT NULL auto_increment PRIMARY KEY,
 name    VARCHAR(64) NOT NULL,
 content BLOB         NOT NULL
)

CREATE TABLE files
(
 id      SERIAL PRIMARY KEY,
 name    VARCHAR(64) NOT NULL,
 content BYTEA        NOT NULL
);

CREATE TABLE dbo.files
(
 id      INT PRIMARY KEY IDENTITY,
 name    VARCHAR(64) NOT NULL,
 content VARBINARY    NOT NULL
)

CREATE TABLE files
(
 id      INT PRIMARY KEY,
 name    VARCHAR(64) NOT NULL,
 content BLOB         NOT NULL
);

It is assumed that the Database Connection to Relational database already exists.
To work with the table, let’s create an API Express Generated service.

On the Test page, we can check how our services are working:

1. Create a record in the files table.
   Name the file test.txt. The file will contain the only sentence test message.
   This content will look like IHRlc3QgbWVzc2FnZQ== in Base64 format.

{
    "name": "test.txt",
    "content": "IHRlc3QgbWVzc2FnZQ=="
}

Response of operation create

{
    "content": "IHRlc3QgbWVzc2FnZQ==",
    "id": 1,
    "name": "test.txt"
}

Take a look at this record in the database client and see that the sentence test message has been saved in the database.

2. Get a record from the files table.

The operation FIND will return the just created record after the file name has been passed in the query:

{
    		"name": "test.txt"
}

The response of FIND operation is

[{
    "content": "IHRlc3QgbWVzc2FnZQ==",
    "id": 1,
    "name": "test.txt"
}]

Example 2. Custom service accepts Binary and returns it.

1. Create a custom service
2. For the component START, specify:
   a. HTTP type as POST
   b. Select Binary (field Type) in the REQUEST BODY section

3. For the component END:
   a. Enable Is binary
   b. Specify Binary body as Binary request
   c. Specify Content-Type as 'application/octet-stream'

4. Open the Test page
5. Any text which is passed in Body will be returned as it is in Response