Getting started with the BlueDolphin API
The BlueDolphin APIs allow you to perform various operations available through our web platform or supporting tools.
BlueDolphin Public API is built using REST principles, which ensures predictable URLs and makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients to be used for an interaction with the API.
Sources
Lets you view, manage, and upload sources in BlueDolphin. Useful for synchronizing the data from your organization.
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 favorite tool that can do REST
Authenticated request
The requests must include the apiKey and tenant headers.
$ curl GET "https://services.eu.bluedolphin.app/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 the admin section of your BlueDolphin environment.
Authentication to the API is performed via HTTP headers.
ApiKey - API key request header
Tenant - Header containing the name of the tenant that 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 similar.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Example
Using GET method, you can get the list of resources or details of a particular instance of a resource.
Below is a request to get a list of data sources.
$ curl GET "https://services.eu.bluedolphin.app/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 JSON 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 mean success, 4xx range mean there was an error in the provided information, and those in the 5xx range indicate server side errors.
Versioned requests
Requests use a path-based versioning scheme.
https://services.eu.bluedolphin.app/api/v1Versioning
When backwards-incompatible changes are made to the API, a new version is released. The current version is v1. Upgrades and breaking changes will be listed in the API reference page under the changelog section.