Protobi REST API

38d87d9852a66eea29da00ae16511664

Updated at October 16th, 2019

Every feature of Protobi that can be accessed via the web user interface can also be accessed programmatically via the Protobi REST API. 

Protobi is a rich client app, so all detailed GUI actions can also be done dynamically within the browser using Protobi's Javascript API. This tutorial describes REST API calls to the Protobi server. If you're reading this article it's likely you're an advanced user with programming knowledge. If you need more assistance contact us at support@protobi.com.

The Protobi REST API can be called from any web interface, including browsers, Node.js, R, Python etc. Examples here are shown using jQuery.

There is also a Node.js SDK which simplifies these calls.

Overview

There are many routes which cover detailed actions like setting project title and images, user permissions, usage logs and change histories.

However, the primary routes you will likely call in practice are to get/set the data as a CSV string, and the elements configuration as a JSON array.

Protobi stores each project as two data elements:

  • CSV data file
  • JSON elements description

The CSV data file is a string in standard CSV format (see IETF 4180 spec). The Elements configuration is an array of element objects.

Authentication

You can call the REST API using your Protobi API Key.
This API key is appended to each URL call as a query parameter, e.g. ?apiKey=<YOUR_API_KEY>.

To get your API key, go to your Protobi account page at https://app.protobi.com/account and press the "Generate API Key" button. Keep this key secret, it allows the holder to login to your account as you.

Download elements

  • Method: GET
  • URL: //v3/datasets/:datasetId/element
  • @param: datasetId unique identifier for dataset
  • Returns: Elements configuration in JSON format

Example (jQuery):

$.ajax({
    type: "GET",
    dataType: "json",
    url: "/api/v3/dataset/<DATASETID>/element",
    success: function (csv, status, xhr) {
        ...
    },
    error: function (xhr, status, err) {
        ...
    }
})

Example (Node.js)

Upload elements

  • Method: POST
  • URL: //v3/datasets/:datasetId/element
  • @param: datasetId unique identifier for dataset
  • Returns: Elements configuration in JSON format

Example (jQuery):

  $.ajax({
        type: "POST",
        url: "/api/v3/dataset/<DATASETID>/element",
        dataType: "json",
        contentType: 'application/json',
        data: JSON.stringify(elements),
        success: function (data, status, xhr) {
            ...
        },
        error: function (xhr, status, err) {
            ...
        }
  })

Download data file

  • Method: GET
  • URL: //v3/datasets/:datasetId/data/:key/:type
  • @param: datasetId unique identifier for dataset
  • @param: key data key, e.g. 'main'
  • @param: type, e.g. csv, sav, or raw to return the original file.
  • Returns: Data file in CSV text format

Example (jQuery):

$.ajax({
    type: "GET",
    url: "/api/v3/dataset/<DATASETID>/data/<FILEKEY>?apiKey=<APIKEY>",
    success: function (csv, status, xhr) {
        ...
    },
    error: function (xhr, status, err) {
        ...
    }
})

Upload data file

  • Method: POST
  • URL: //v3/datasets/:datasetId/data/:key/:type
  • @param: datasetId unique identifier for dataset
  • @param: key data key, e.g. 'main'

Send the data as form data under attribute file with sub-attributes filename and content-type. To upload CSV data, use content-type: "text/csv". To upload SAV data, use content-type: "'application/octet-stream'"

Example (jQuery)

var fd = new FormData();
fd.append('file', new File([new Blob([csv])], filename));

$.ajax({
    url: url,
    data: fd,
    processData: false,
    contentType: 'text/csv',
    type: 'POST',
    success: console.log,
    error: console.error
});

Helper libraries for R and Node.js

You can use Protobi R package https://github.com/protobi/protobi-r which wraps the REST API and reads Protobi data into and from R data frames, and represents value labels as factors:

data <- protobi.get_data(PROJECTID, TABLEKEY, APIKEY)
protobi.put_data(data, PROJECTID, TABLEKEY, APIKEY)
`

There is also a Node.js library https://github.com/protobi/protobi-node-sdk which wraps the REST API for calls from Node.js servers or scripts:

protobiAPI.uploadData(data, PROTOBI_PROJECT_ID, "main", null, function (err) {
  if (err) return callback(err);
  console.log("DATA uploaded")
})

Was this article helpful?