Dit artikel is vertaald met behulp van AI en kan kleine onnauwkeurigheden bevatten. Raadpleeg de Engelse versie voor volledige nauwkeurigheid.
Overzicht
Welkom bij de BlueDolphin Public API Quick Start Guide. Deze gids helpt je snel aan de slag te gaan met de API en geeft voorbeelden van de belangrijkste functionaliteiten.
Installatie
Add-On
De BlueDolphin Public API is standaard beschikbaar voor alle tenants, zodat je API-aanroepen kunt doen op je tenant.
Als de Public API niet is ingeschakeld voor je tenant (bijvoorbeeld bij oudere tenants), krijg je bij API-aanroepen een 403 Forbidden-foutmelding.
Locatie
Dit zijn de locaties in productie. Afhankelijk van de cluster waar je tenant zich bevindt, is de basislocatie van de API als volgt:
Cluster | URL | Open API Documentatie |
EU | ||
US |
Liveness
Om te testen of de Public API-service actief is op de cluster, kun je een oproep doen naar de liveness-endpoint. De endpoint geeft ‘Healthy’ terug als de service beschikbaar is.
Voorbeeld met cURL:
curl https://public-api.eu.bluedolphin.app/liveness
Een geslaagde oproep geeft een 200 OK HTTP-statuscode terug met de volgende body:
Healthy
Tenant-specifieke endpoint
De meeste endpoints zijn tenant-specifiek. Deze endpoints verwachten een TENANT-header met de naam van de tenant.
Als deze header vereist is en niet wordt meegegeven, krijg je een 401 Unauthorized HTTP-statuscode met de volgende 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" ] }}
Als deze header wordt meegegeven met een onjuiste tenant-waarde, krijg je een 401 Unauthorized HTTP-statuscode met de volgende 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" ] }}
Authenticatie
Om te beginnen moet je je verzoeken authenticeren met een API-sleutel. Voeg je API-sleutel toe aan de request headers bij elke API-aanroep.
Genereer een API-sleutel
Om een API-sleutel voor de public API in BlueDolphin aan te maken, moet je de Admin-gebruikersrol hebben.
User Key Management API-sleutel
De key management API-sleutel wordt alleen gebruikt om API-sleutels voor specifieke gebruikers aan te maken. Deze sleutel kan niet worden gebruikt om gegevens uit BlueDolphin op te halen of te wijzigen.
Om een User Key management API-sleutel aan te maken in BlueDolphin, ga je naar Admin > Public API keys en kies je het bereik User Key Management:
Let op: de nieuwe sleutel kan na dit moment niet meer worden opgehaald. Je moet deze sleutel zelf opslaan voor toekomstig gebruik en naslag.
User API-sleutel
Om gegevens op te halen en te wijzigen in BlueDolphin, moet je een "User API-sleutel" aanmaken. Deze sleutel heeft toegang tot BlueDolphin met de rechten van de gebruiker. Hiervoor moet je een specifieke sleutel voor de gebruiker aanmaken met de User Key management API-sleutel.
Gebruik de User Key management API-sleutel op de /user-api-keys endpoint.
Om een User API-sleutel aan te maken heb je het volgende nodig:
Een geldige User Key management API-sleutel (zie de instructies in de bovenstaande sectie)
De
user_idvan de gebruiker waarvoor je de API-sleutel wilt aanmakenDe tenantnaam
Naam van de sleutel: een string waarmee je het gebruik van de sleutel kunt herkennen. Dit kan elke naam zijn.
Vervaldatum: de datum waarop de sleutel verloopt. Dit moet een datum in de toekomst zijn.
De user_id in dit verzoek is een unieke identificatie van de bestaande gebruiker waarop de sleutel gebaseerd moet zijn. Deze sleutel vind je in BlueDolphin in het gedeelte Admin onder Gebruikers. Het user_id-veld is de laatste parameter in de URL, bijvoorbeeld: https://bluedolphin.app/<tenant>/admin/users/<user_id>
Zodra je deze informatie hebt, kun je een POST-verzoek sturen naar de endpoint /user-api-keys. Hier is een voorbeeld van een API-verzoek om een nieuwe user API-sleutel aan te maken:
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": "Naam van de sleutel", "user_id": "6253e0ccad3fbfd674bba765", "expiration_date": "2024-12-12"}'
Een geslaagde oproep geeft een 201 OK HTTP-statuscode terug met de volgende body:
{ "id": "63c57b3882345012d9e7a157", "key": "65662264-dd0e-46eb-9b11-ab2fb426bbc2"}
Let op: de nieuwe sleutel kan na dit moment niet meer worden opgehaald. Je moet deze sleutel zelf opslaan voor toekomstig gebruik en naslag.
Gebruik
De aangemaakte user API-sleutel kan worden gebruikt voor authenticatie door de X-API-KEY-header te gebruiken. De user API-sleutel gebruikt de rechten van de gebruiker waarvoor de sleutel is aangemaakt.
Voorbeeld met CURL:
curl --location 'https://public-api.eu.bluedolphin.app/v1/workspaces' \--header 'tenant: mytenant' \--header 'x-api-key: YOURAPIKEYSECRET'
Een geslaagde oproep geeft een 200 OK HTTP-statuscode terug met een body zoals hieronder:
[ { "id": "xxxxxxxxxxxxxxxxxxxxxx", "name": "My Workspace", "status": 0, "is_root": true }]
Voorbeelden
Maak een 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"}'
Een geslaagde oproep geeft een 201 OK HTTP-statuscode terug met de volgende body:
{ "id": "644779a07470b332c82b8dg0", "object_title": "HiBob"}
Er is nu een nieuw object aangemaakt met het id 644779a07470b332c82b8dg0.
De response bevat ook de location-header die de URL aangeeft van het nieuw aangemaakte object. Dus, de location-header voor het vorige voorbeeld zou zijn: https://public-api.eu.bluedolphin.app/v1/objects/644779a07470b332c82b8dg0.
Object en vragenlijst (BOEM) velden bijwerken
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": "Nieuwe Applicatie Naam", "object_properties": [ { "name": "Naam", "value": "Applicatie Update" } ], "boem": [ { "id": "58edcaf2829327621dfff9e5", "name": "Applicatie 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": "" } ] } ] }'
Een geslaagde oproep geeft een 200 OK HTTP-statuscode terug met de volgende body:
{ "id": "643e9020d97c6a7e28775377", "object_title": "Nieuwe Applicatie Naam", "type": { "id": "640b3d7d4a28b925fcf8b9b4", "name": "Applicatie", "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": "Naam", "value": "Applicatie Update" } ], "boem": [ { "id": "58edcaf2829327621dfff9e5", "name": "Applicatie Info", "items": [ { "field_type": "dropdown", "id": "dfbf6463-c17d-4107-8903-51cf0968267c", "name": "Is deze applicatie een Single Point of Failure (SPOF)?", "value": "" }, { "field_type": "currency", "id": "e59a6e32-bef9-430c-86dc-9dbc31e49b46", "name": "Schatting van jaarlijkse applicatiekosten", "value": "" }, { "field_type": "relation", "id": "6cb46f87-b1a6-4fbd-9043-1f32b4a8f9d2", "name": "Wat zijn de functies van deze applicatie?", "value": "532fff94b41281c17ce263b7|58a0378a63bab70ae83525d9" }, { "field_type": "dropdown", "id": "c29271a2-7634-4abc-962a-bb2af522c547", "name": "Welke fase is van toepassing op deze applicatie?", "value": "" } ] } ], "related_objects": [ { "relationship_id": "21435a647f12172fc4cc72f0", "object_id": "64369407346524508417d7b2", "object_title": "Acquisitie en ontwikkeling van bouwkavels", "type": { "id": "5d25c4bc0c0ba6e79c23d123", "name": "Bedrijfsproces", "name_internal": "business_process" }, "relationship": { "template_id": "5123e9d68ccee096c838fe93", "name": "gebruikt door", "type": "usedby" } } ]}