Getting started with BlueDolphin API

The BlueDolphin APIs allows you to perform various operations that you do with our web platform or supporting tools.

BlueDolphin Public API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API.

Sources

Lets you view, manage and upload sources in BlueDolphin. Useful for synchronizing the data from your organisation!

Reports

Lets you retrieve output of the reports from your BlueDolphin environment.

File Sharing

Provides the glue to work with the sources and report data.

First steps

To start using BlueDolphin APIs to create integrations, you need to have:

A BlueDolphin environment.
An API key. If you don't have one see here.
And your favourite tool that can do REST.

Authenticated request

The requests must include the apiKey and tenant headers.

$ curl GET "https://services.
bluedolphin.valueblue.nl/api/v1
/datasource-reports" 
-H "apiKey: f08a2bb9-3ab4-451a-9099-2ef531375147" 
-H "tenant: contoso"

Authentication

The BlueDolphin API uses API keys to authenticate requests. You can view and manage your API keys in admin section of your BlueDolphin environment.

Authentication to the API is performed via HTTP headers.

ApiKey - the API key request header.
Tenant - the header that contains the name of the tenant you need to access.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Examples

Using GET method, you can get the list of resources or details of a particular instance of a resource.

To get a list of datasources

$ curl GET "https://services.
bluedolphin.valueblue.nl/api/v1
/datasources"
-H "apiKey: f08a2bb9-3ab4-451a-9099-2ef531375147" 
-H "tenant: contoso"

HTTP methods

BlueDolphin API uses appropriate HTTP verbs for every action.

Name

Description

GET

Used for retrieving resources.

POST

Used for creating resources and performing resource actions.

PUT

Used for updating resources.

PATCH

Used for updating a specific detail of the resource.

DELETE

Used for deleting resources.

Response structure

The response structure for the export API follows the below format.

{
    "error_code": 0,
    "error_message": null,
    "error_message_explain": null,
    "data": {
        "file_name": "..."
    }
}

Response

Responses will be in the JSON format and will have the following common format.

Name

Description

error_code

BlueDolphin error code. This will be zero for a success response and non-zero in case of an error.

error_message

In case of the failure of an API call this will contain a short message describing the error, otherwise it's null.

error_message

In case of a failure of an API call this might contain more information on the error.

data

Comprises the invoked API’s Data.

HTTP status codes

2xx

Success

4xx

Bad request sent to server

5xx

Server side error

Errors

BlueDolphin uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicates server side errors. Commonly used HTTP status codes are listed below.

Versioned requests

Requests use a path-based versioning scheme.

https://services.bluedolphin.
valueblue.nl/api/v1

Versioning

When backwards-incompatible changes are made to the API, a new version is released. The current version is v1. Upgrades, breaking changes will be listed in the API reference page under changelog section.