Data Foundry Platform API v1

The v1 API is meant and designed for two purposes:

• allowing for the design and implementation of different front-ends with the DF backend
• allowing for authenticating users from Data Foundry in other applications

The second point is important to prevent personally-identifiable data being stored on insecure servers.

General information

The API works with GET or POST calls to a series of different endpoints. All calls need to have a header api-key with the API key. If you would like to use the API, contact us to get your API key. You will also get access to a staging server for testing your integration.

The following documentation uses the jQuery Javascript library to make the API calls, but any other library or platform that supports GET and POST calls is fine.

In the following, we go through all API calls from registration and login to creating and accessing projects and datasets. We assume that the variables server_address and api-key are defined before:

var server_address = "https://123.456.789.123"
var api_key = "acb123"

All calls result in a JSON response that (1) indicates success or failure and (2) contains a data payload with the requested information:

// success
{
	"result": "ok",
	"data": ...
}

// failure
{
	"result": "ok",
	"message": "the error message or explanation, with details"
}

All calls except the register and login calls need an additional header field api-token that can be obtained from the succesful response to a login call (see below).

Authentication API

The authentication API is about using the Data Foundry account system to authenticate users for other applications. Further functions are available from the full API (different API key).

Login user

To login a user you need to provide a username and password for this user. Users can be registered with the call above or through the default front-end. You can provide an optional timeout parameter to control the session timeout.

$.ajax({
    url: server_address + '/api/v1/login',
    type: 'POST',
    data: {
        'username': 'ex@example.com',
        'password': 'something',
        'timeout': 3600
    },
    headers: {
        'api-key': api_key
    },
    success: function (result) {
        console.log(result)
        // grab the api-token from here, it will be necessary for all internal requests
    },
    error: function (error) {
        console.error(error)
    }
});

The response to a successful login call contains several items: email, first_name and last_name are given from the logged in user as well as the api-token, which you need for all other calls to API.

If you want to use the API to authenticate Data Foundry user for a separate application, you can just use the login call to obtain name and email of the user.

Logout

To logout the user, use a GET request:

$.ajax({
    url: server_address + '/api/v1/logout',
    type: 'GET',
    headers: {
        'api-key': api_key
    },
    success: function (result) {
        console.log(result)
    },
    error: function (error) {
        console.error(error)
    }
});

Full API

The full API gives access to a lot more functionality than the authentication API. For this API, a different key is necessary.

Register user

The register user call attempts to register a single user in the Data Foundry, given the email, first and last name and twice the password.

$.ajax({
    url: server_address + '/api/v1/user/register',
    type: 'POST',
    data: {
        'email': 'ex@example.com',
        'password': 'something',
        're_password': 'something',
        'first_name': 'example firstname',
        'last_name': 'example lastname'
    },
    headers: {
        'api-key': api_key
    },
    success: function (result) {
        console.log(result)
    },
    error: function (error) {
        console.error(error)
    }
});

The response will be either success or failure (see above), no data additional will be provided with the success response.

Other calls

Upon request.