API Guide

Using the Marple API

1 Arguments and Responses

There are two ways of passing arguments to an endpoint: either encoded as key-value pairs in the URL or encoded as JSON in the body of the request. This depends on the endpoint, in general GET requests will use URL encoding, while POST requests will use JSON encoding. The full specification of all endpoints can be found at the bottom of the page. Here is an example of both methods in Python:

params = {'path': path}
r = requests.get(f'{API_URL}/sources/lookup', headers=auth_header, params=params)

body = {'path': '/', 'new_folder_name': 'new_folder'}
r = requests.post(f'{API_URL}/library/folder/add', headers=auth_header, json=body)

Requests will always return data as JSON with the following structure:

{"request_time": time, "message": data}

It will contain both the time the server has taken to process the request and the actual output. Decode and access the message key to extract the result:

response = requests.get(f'{API_URL}/version', headers=auth_header)
version = response.json()['message']
print(version) # 3.3.0

Or using the Marple SDK:

from marple import Marple
m = Marple(ACCESS_TOKEN)
response = m.get('/version')
print(response.json()['message']) # 3.3.0

2 Uploading and Importing Files

In Marple files are uploaded onto a file server and then parsed into our database which we call 'importing'. Once a file has been imported into the database it is referred to as a 'source'

1. `POST /library/file/upload`

Upload a file onto the file server. URL query parameters:

path: the path to the directory on the file server where the file should be uploaded

File body parameters:

file: the file contents

=> Returns "OK", and confirms the path where the file is uploaded

#Setup
API_URL = 'https://app.marpledata.com/api/v1'
endpoint = '/library/file/upload'
token = '...'
auth_header = {'Authorization': f'Bearer {token}'}
‍
#Arguments
files = {'file': open('myfile.csv', 'rb')}
target_dir = '/'  # file server root dir
target_dir = '/sub_dir' # or a subdirectory

#Request
r = requests.post(
  f'{API_URL}{endpoint}', 
  headers=auth_header,
  params={'path': target_dir}, 
  files=files
)

#Response
r.json()['message'] == {'status': 'OK', 'path': 'sub_dir'}

2. `POST /library/file/import`

Start importing a file into the database JSON body parameters:

path: the path to where the file is located on the server
plugin: the plugin to be used for importing the file
config: (optional) the configuration for the plugin

=> Returns the source_id of the file in the database, and the metadata associated with the file

endpoint = '/library/file/import'
path = '/sub_dir/myfile.csv'
plugin = 'csv_plugin'

r = requests.post(
  f'{API_URL}{endpoint}', 
  headers=auth_header,
  json={'path': path, 'plugin': plugin}
)

r.json()['message'] == {
  'source_id': 1,
  'metadata': { # most plugins don't support automatic metadata extraction
    'test_reference': 14,
  }
}

3. `GET /sources/status`

Monitor the progression of the file import process URL query parameters:

id: source id or array of source ids for which to request the status.

To pass an array as a query parameter use the following syntax: api_url/sources/status?id=1,2,3,...

=> Returns an array of status codes

endpoint = '/sources/status'
source_id = 1

r = requests.post(
  f'{API_URL}{endpoint}',
  headers=auth_header,
  params={'id': source_id}
)

r.json()['message'] == {[{
  'source_id': 1,
  'status': 100
}]}

3 Adding Metadata

Metadata can be manipulated using the /library/metadata endpoints. Metadata is always coupled to files using the source_id and not the file name. The source id associated with a file can be found using the /sources/lookup endpoint.

1. `GET /sources/lookup`

Get source id associated with file. URL query parameters:

path: full file path of file to lookup

=> Returns the source_id of the file

endpoint = '/sources/lookup'
path = '/sub_dir/myfile.csv'

r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                  params={'path': path})

2. `POST /library/metadata`

Add metadata to a source JSON body parameters:

source_id: the source to add the metadata to
path: (optional) If the file does not yet have a source_id it can be referenced by its path. This function will return the source id assigned to the file in this case
metadata: Key-value pairs to add to metadata.

=> Returns source_id and "OK" message

source_id = 1
metadata = {'test_operator': 'Arthur', 'test_reference': 'BX-14'}

endpoint = '/library/metadata'
r = requests.post(
  f'{base_url}{endpoint}',
  headers=auth_header,
  json={
    'source_id': source_id,
    'metadata': metadata
  }
)

A project can be shared using the /library/share endpoints. Make sure that the target project exists in the app before using these endpoints.

Generate a new share link id JSON body parameters

workbook_name: name of the project you wish to share
source_ids: sources to include in the share

=> Returns new share id

endpoint = '/library/share/new'
name = 'example'
source_ids = [1,2,3]
‍
r = requests.post(
  f'{base_url}{endpoint}',
  headers=auth_header,
  json={
    'workbook_name': name,
    'source_ids': source_ids
  }

Add data to share id JSON body parameters:

workbook_name: change project for this share
source_ids: Source ids to add to share

=> Returns new share id with updated content

share_id = '1234567890abcdef'
endpoint = f'/library/share/{share_id}/add'
source_ids = [4,5,6]
‍
r = requests.post(
  f'{base_url}{endpoint}',
  headers=auth_header,
  json={
    'workbook_name': name,
    'source_ids': source_ids
  }
)

Genrate a sharable link which opens the project with its source ids JSON body parameters:

url: (optional) set base URL for the share link

=> Returns clickable link

share_id = '1234567890abcdef'
url = 'https://yourcompany.marpledata.com'
endpoint = f'/library/share/{share_id}/link'
‍
requests.get(
  base_url + endpoint,
  auth=marple_auth,
  args={'url': url}
) # Returns https://yourcompany.marpledata.com/?share=1234567890abcdef

5 API Example Repository

Marple maintains a public repository with an example API usecase: 🔗 https://gitlab.com/marple-public/marple-api-exampleThis script runs a simulated experiment, logs the data, uploads and imports it into marple and then generates a share link ready for visualisation.In the public repository there are example scripts for both Python and MATLAB.

6 API Reference

Marple Swagger API Reference

PreviousPython

Last updated 1 month ago

1 Arguments and Responses

2 Uploading and Importing Files

1. POST /library/file/upload

2. POST /library/file/import

3. GET /sources/status

3 Adding Metadata

1. GET /sources/lookup

2. POST /library/metadata

4 Sharing Projects and Sources

1 POST /library/share/new

2 POST /library/share/<share_id>/add

3. POST /library/share/<share_id>/link