Data API & Test Files

Introduction

Data API allows you to manipulate DragOnce data via API calls. You can define API profiles, Authentication Information (such as OAuth 2.0, API Key) for each App. And each profile can consist of multiple endpoints representing CRUD operations for data, which will result in API endpoints to allow you to request over the network.

Configuration

Setup

1. For example, we have the following form and workflow created in an app called DataAPI Demo

2. Go to Data API configuration page from the top right corner of the Launch Board

3. Enter the App

4. Click add button to add a profile

5. On the page shown, fill in all details on the right-side panel.

Then click "Save".

•  Name: An readable name to be shown in the list.

• URL: A path segment to be used in URL.

• Client ID & API Key: Permission controlling.

6. The page will refresh after saving, more info will be shown on the left side. Click on "+ End Point" and select a target action of the endpoint to be created. After selecting an action, go to the related sections below for further information.

Actions

1. To create an endpoint, fill in the settings on the right side. Then click "Submit".

• URL: The URL segment in URL.

• Form: The target form of the endpoint to bind. (After selecting a form, the left side UI will be updated with form information).

• Client ID / API Key: Permission controlling. You can choose to inherit profile setting/override with selected Client ID / API Key here.

2. For every endpoint, there is a toggle next to the name area. This can be used to temporarily disable the endpoint.

Create

Mapping

Each row represents a parameter/variable/hardcode value to be mapped to a widget when creating a record. Hovering on the selection area will allow you to choose different options. Such as:

Workflow Action

Only selected actions are allowed to be jumped to when creating a record.

Read

Parameter

Defines parameters to be accepted in network requests.

Record Filter

Filtering area which can use values including parameters to filter records.

Mapping

Each row represents a widget value to be mapped to a key in JSON response.

For example, the above mapping will result in each object containing the following key:

{

    "input_box_a": "Value of input box",

    "datatime_b": 1632478929

}

Sorting

Controls the order of output data.

Workflow Action

Defines a custom mapping of values of workflow actions in output to show.

Update

Allow update multiple record

The checkbox is present at the top-right corner. Checking it will allow you to update multiple records at once. Otherwise, the request will result in an error if multiple records are found after the filter.

Parameter

Defines parameters to be accepted in network requests.

Record Filter

Filtering area which can use values including parameters to filter records.

Mapping

Each row represents a parameter/variable/hardcode value to be mapped to a widget when updating a record. Hovering on the selection area will allow you to choose different options. Such as:

See Mapping Options for more details.

If a row is left empty, then the value of the widget of that row will be kept as-is and will NOT be updated.

Workflow Action

Only selected actions are allowed to be jumped to when creating a record.

Delete

Allow delete multiple record

The checkbox is present at the top-right corner. Checking it will allow you to delete multiple records at once. Otherwise, the request will result in an error if multiple records are found after the filter.

Parameter

Defines parameters to be accepted in network requests.

Record Filter

Filtering area which can use values including parameters to filter records.

Parameter Types

Mapping Options

Making Request(s)

Basic Flow

1. Setup and obtain authentication info using one of the available methods (OAuth 2.0 / API Key).

2. Setup the profile & endpoint to be used.

3. Open the swagger document for reference before proceeding to the next step

4. (OAuth 2.0 only) Request for an access token .

5. Perform request to the endpoint

Note: You may want to use common API(s) before performing this request to obtain IDs or upload files, etc.

Below are some points to note when making a request:

a. OAuth 2.0 access token / API Key is required for all API calls.

b. Request method: POST unless otherwise specified in the swagger document

c. Parameter "env": Environment ID. Should always be provided and the same as the profile's environment. 

Additional Flow for upload/delete files and images

General Concept

1. To upload a file/image to DragOnce, you need to use the corresponding Common API. However, this API only performs the upload task to the backend and will not be shown when viewing the record.

2. Common API "Upload File" and "Upload Image" considers the widget type but not the file type. So:

i. Use "Upload FIle" for the File Uploader widget.

ii. Use "Upload Image" for Image Uploader widget.

3. The displayed files are controlled by the hashmap provided when creating/updating a record. Only the files which have their file ID in the hashmap will be shown when viewing the record.

4. You can upload & delete files at the same request by adding new IDs to hashmap and removing old IDs at the same time.

5. To modify (a.k.a. replace) a file, there is no direct API to perform this. You need to follow the steps below:

i. Upload a new file first. 

ii. Replace the ID (615bc4196ca48fdf91000002) of the target file with a new file ID (615bc4196ca48fdf91000020, and also its information in an uploader widget (XXXXXX)

See the following example:

{

XXXXXX:

} 

6. As stated in swagger document, the hashmap value should be as below

For Upload FIle as temporary storage

1. Upload the file using a common API.

* The request body should be in "multipart/form-data" when using these common API

a. Use "Upload FIle" for the File Uploader widget

b. Use "Upload Image" for the Image Uploader widget.

2. Markdown the responded file ID.

3. Update the hashmap

a. For Create

i. Start typing a json hashmap from scratch

The hashmap should look like

{

  "615bc4196ca48fdf91000010": {

    "n": "new_file.pdf",

    "s": "456"

  }

}

b. For Update

i. Retrieve the record from DragOnce first

ii. Retrieve the hashmap of files of the target file/image uploader widget

iii. Add an entry to the hashmap for the new file

For Delete file

1. Retrieve the record from DragOnce first

2. Retrieve the hashmap of files of the target file/image uploader widget

3. Remove the not needed ID from hashmap

4. Set the updated hashmap as a value for the file/image uploader widget in the update request

For example:

Example

Take an update endpoint for the above form and workflow as an example.

1. Setup and obtain authentication info using one of the available methods (OAuth 2.0 / API Key).

See OAuth 2.0 / API Key below for more detail.

* The example below will use OAuth 2.0 as a demo.

2. Setup the endpoint for update action.

a. On the right-side panel:

i. Fill in the endpoint URL

ii. Choose a target form

iii. Choose the desired authentication method

(Here, we select the client ID we previously created.)

b. On the left-side panel:

i. Check the "Allow update multiple record"

* Such that when the record filtered result has multiple rows, all will be updated with new values.

ii. Under the section "Parameter", set up 3 parameters for the request.

1 for filtering, 1 for new value and 1 for target workflow state.

iii. Set up a record filter using the filter value parameter.

iv. Define the mapping as follows:

Explaining the following setup:

• "DateTime B" will be set to the current time on every update.

• "Input Box A" & Workflow will be provided by request parameters.

• Current Stakeholders will be hardcoded to "testuser1" whenever updated.

v. Setup the workflow actions to be used.

1. Check the workflow state which allows the record to be updated via this End Point.

2. Provide a custom key to be used as a value in request / hardcoded value.

vi. The full picture of the final setup should be as follows:

3. Before making a request, create some test records in the corresponding form of DragOnce.

4. To start making a request, request an access token using OAuth 2.0 client ID & 

client secret.

(If you are using API Key, please skip this step.)

Method: GET

URL format: https://dataapi.dragonce.com/{subscriber_id}/auth/access_token

Query Parameters:

• client_id: (Obtain from OAuth 2.0 client ID setup)

• client_secret: (Obtain from OAuth 2.0 client ID setup)

5. Store the responded access_token

6. Prepare the update request:

Since we do not have a file widget here, we will use “x-www-form-urlencoded” as the encoding method of the body of the request.

(If there is a file, please use “form-data”)

Method: POST

URL: (Copy from the endpoint setting panel)

Parameters:

• access_token: (Obtain in step 4)

• env: (Environment ID, see Obtain Environment ID)

• {Other parameters defined in endpoint}, in this case, we will provide "new_value", "filter_value" and "workflow_param"

7. he response will provide statistics of the request.

Here we can see 2 records are being updated and their IDs.

8. Note the value of the records is being updated in DragOnce after the request.

Appendix

Obtain Environment ID

1. Go to App List

2. Click the ID button

3. Click the Environment ID button in the side menu.

4. Copy the corresponding ID of the target environment.

OAuth 2.0

Obtain Client ID & Client Secret

1. Go to Data API

2. Click "Client ID" on the left menu

3. Click the add button to add a new Client ID

4. Enter the name and description

5. Markdown the client ID & client secret

OAuth 2.0 Usage

1. Issue a GET request to retrieve an access token with query parameters

(Set "client_id" and "client_secret" in body)

* Please see "Authentication APIs" in swagger document

2. API returns the response, mark down the value of access_token

3. In the normal Data API call, use as follows:

API Key

Obtain API Key

1. Go to Data API

2. Click "API Key" on the left menu

3. Click the add button

4. Enter name and description of API Key

5. Markdown the API Key

API Key Usage

1. Use in Data API requests as follows:

(Set "X-API-Key" in the header)

* No need to use Authentication APIs, just directly call the Data API

Common APIs

For each common API, there are limits on which type of endpoint(s) can use that common API. Please refer to the swagger document for details.

Authentication is also applied and required for these common APIs as they are bound with the corresponding endpoint.

Some common APIs require the parameter "widget_key".

For create/update/delete endpoints, it means one of the parameters you defined in the endpoint settings.

For read endpoints, it means one of the response keys in the "Mapping" section in the endpoint settings.