Overview

Welcome to the BlueDolphin Public API Quick Start Guide. This guide is designed to get you up and running with the API swiftly, providing examples that showcase its key functionalities. 

 

Setup

Add-On

The Public API is an Add-on that needs to be enabled on your BlueDolphin tenant before you are capable to do API calls on your tenant. Contact your Account Manager to get the Add-on. If the add-on is not activated, any calls to the BlueDolphin public API will result in a 403 Forbidden error.

Location

These are the locations in production. Depending in which cluster your tenant is located, the API base location is as follows:

 

Liveness

To test whether the Public API service is up and running on the cluster, a call to the liveness endpoint can be done. The endpoint will return ‘Healthy’ when the service is available.

Example using cURL:

curl https://public-api.eu.bluedolphin.app/liveness

 

A successful call returns a response with a 200 OK HTTP status code and the following body:

Healthy

 

Tenant specific endpoint

Most endpoints are tenant specific. Those endpoints expect a TENANT header that holds the name of the tenant.

When this header is required and not given, a call returns a response with a 401 Unauthorized HTTP status code and the following body:

{
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
    "title": "One or more validation errors occurred",
    "status": 401,
    "traceId": "c0a5eacd-8aa7-4571-b4c8-c2dd03d16c84",
    "errors": {
        "tenant": [
            "Tenant header missing or empty"
        ]
    }
}

 

When this header is given with an incorrect tenant value, a call returns a response with a 401 Unauthorized HTTP status code and the following body:

{
    "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
    "title": "One or more validation errors occurred",
    "status": 401,
    "traceId": "40f720cb-52cf-43fe-9c6f-fe68b14ee53d",
    "errors": {
        "tenant": [
            "Unknown tenant specified"
        ]
    }
}

 

Authentication

To begin, you'll need to authenticate your requests using API key authentication. Include your API key in the request headers for every API call.

 

Generate an API key

To create an API key for the public API in BlueDolphin, you must have an Admin user role. 

 

User Key Management API key

The key management API key is only used to create API keys for specific users. This key can't be used to get or change data from BlueDolphin.

1. To create a User Key management API key in BlueDolphin navigate to Admin > Public API keys and choose the User Key Management scope:

 

Please be aware that the new key cannot be retrieved after this point. You will need to store this key yourself for further usage and reference.

 

User API key

To get and change data in BlueDolphin you need to create a "User API key". This key can access BlueDolphin with the rights of the user. To do this, we need to create a specific key for the user with the User Key management API key. 

 

Use the User Key management API key on the /user-api-keys endpoint.

To create a User API key you need the following:

• A valid User Key management API key (refer to the instructions in the section above)
• The  user_id  of the user you want to create the API key
• The tenant name
• Name of the key: A string that helps you identify the use of the key. It can be any name.
• Expiration date: The date when the key will expire. This should be a date in the future. 

The user_id in this request is a unique identifier for the existing user that the key needs to be based on. This key can be found in BlueDolphin in the Admin section under Users. The user_id field is the last parameter in the URL, for example: https://bluedolphin.app/<tenant>/admin/users/<user_id>

 

Once you have this information you can send a POST request to the endpoint /user-api-keys. Here is a sample API request which shows how to create a new user API key:

curl -L 'https://public-api.eu.bluedolphin.app/v1/user-api-keys' \
-H 'x-api-key: KEYMANAGEMENTAPISECRET' \
-H 'tenant: yourtenantname' \
-H 'Content-Type: application/json' \
-d '{
    "name": "BrandNewKey",
    "user_id": "643e9020d97c6a7e28665255",
    "expiration_date": "2024-12-12"
}'

 

A successful call returns a response with a 201 OK HTTP status code and the following body:

{
    "id": "63c57b3882345012d9e7a157",
    "key": "65662264-dd0e-46eb-9b11-ab2fb426bbc2"
}

 

Please be aware that the new key cannot be retrieved after this point. You will need to store this key yourself for further usage and reference.

 

Usage

The created user API key can be used for authentication by using the X-API-KEY header. The user API key uses the permissions of the user that the key was created for.

Example using cURL:

curl --location 'https://public-api.eu.bluedolphin.app/v1/workspaces' \
--header 'tenant: mytenant' \
--header 'x-api-key: YOURAPIKEYSECRET'

 

A successful call returns a response with a 200 OK HTTP status code and a body like the following body:

[
    {
        "id": "xxxxxxxxxxxxxxxxxxxxxx",
        "name": "My Workspace",
        "status": 0,
        "is_root": true
    }
]

 

Examples

Create an object

curl -L 'https://public-api.eu.bluedolphin.app/v1/objects' \
-H 'x-api-key: YOURAPIKEYSECRET' \
-H 'tenant: yourtenantname' \
-H 'Content-Type: application/json' \
-d '{
    "object_title": "HiBob",
    "object_type_id": "640b3d7d4a28b925fcf8b8bc",
    "workspace_id": "63f620763279a10a8eefa7b0"
}'

 

A successful call returns a response with a 201 OK HTTP status code and the following body:

{
    "id": "644779a07470b332c82b8dg0",
    "object_title": "HiBob"
}

 

A new object with the id 644779a07470b332c82b8dg0 has now been created.

The response also includes the location response header that indicates the URL to the newly created object. So, the location header for the previous example would be https://public-api.eu.bluedolphin.app/v1/objects/644779a07470b332c82b8dg0.

 

Update object and questionnaire (BOEM) fields

curl -L -X PATCH 'https://public-api.eu.bluedolphin.app/v1/objects/643e9020d97c6a7e28775377' \
-H 'x-api-key: YOURAPIKEYSECRET' \
-H 'tenant: yourtenantname' \
-H 'Content-Type: application/json' \
-d '{
    "object_title": "New Application Name",
    "object_properties": [
        {
            "name": "Name",
            "value": "Application Update"
        }
    ],
    "boem": [
           {
            "id": "58edcaf2829327621dfff9e5",
            "name": "Application Info",
            "items": [
                {
                    "id": "dfbf6463-c17d-4107-8903-51cf0968267c",
                    "value": ""
                },
                {
                    "id": "e59a6e32-bef9-430c-86dc-9dbc31e49b46",
                    "value": ""
                },
                {
                    "id": "6cb46f87-b1a6-4fbd-9043-1f32b4a8f9d2",
                    "value": "532fff94b41281c17ce263b7|58a0378a63bab70ae83525d9"
                },
                {
                    "id": "c29271a2-7634-4abc-962a-bb2af522c547",
                    "value": ""
                }
            ]
        }
    ]
	}'

 

A successful call returns a response with a 200 OK HTTP status code and the following body:

{
    "id": "643e9020d97c6a7e28775377",
    "object_title": "New Application Name",
    "type": {
        "id": "640b3d7d4a28b925fcf8b9b4",
        "name": "Application",
        "name_internal": "application_component"
    },
    "workspace": {
        "id": "63f621863279a10a8eefa7a9",
        "name": "mainworkspace"
    },
    "created_information": {
        "user_id": "63f6322c275ab8fea702f9b7",
        "first_name": "Hannah",
        "last_name": "Blake",
        "date": "2023-04-18T12:42:08.075Z"
    },
    "modified_information": {
        "user_id": "000000000000000000000000",
        "first_name": "BlueDolphin",
        "last_name": "",
        "date": "2023-06-22T19:25:23.021Z"
    },
    "status": 2,
    "object_properties": [
        {
            "name": "Name",
            "value": "Aplication Update"
        }
    ],
    "boem": [
        {
            "id": "58edcaf2829327621dfff9e5",
            "name": "Application Info",
            "items": [
                {
                    "field_type": "dropdown",
                    "id": "dfbf6463-c17d-4107-8903-51cf0968267c",
                    "name": "Is this application Single Point of Failure (SPOF)?",
                    "value": ""
                },
                {
                    "field_type": "currency",
                    "id": "e59a6e32-bef9-430c-86dc-9dbc31e49b46",
                    "name": "Estimate of annual application costs",
                    "value": ""
                },
                {
                    "field_type": "relation",
                    "id": "6cb46f87-b1a6-4fbd-9043-1f32b4a8f9d2",
                    "name": "What are the functions of this application?",
                    "value": "532fff94b41281c17ce263b7|58a0378a63bab70ae83525d9"
                },
                {
                    "field_type": "dropdown",
                    "id": "c29271a2-7634-4abc-962a-bb2af522c547",
                    "name": "Which stadium applies to this application?",
                    "value": ""
                }
            ]
        }
    ],
    "related_objects": [
        {
            "relationship_id": "21435a647f12172fc4cc72f0",
            "object_id": "64369407346524508417d7b2",
            "object_title": "Acquisition and development of building lots",
            "type": {
                "id": "5d25c4bc0c0ba6e79c23d123",
                "name": "Business Process",
                "name_internal": "business_process"
            },
            "relationship": {
                "template_id": "5123e9d68ccee096c838fe93",
                "name": "used by",
                "type": "usedby"
            }
        }
    ]
}