Data Catalogue Specific API Keys
We have discussed API keys under Administrator Tasks. In the Data Catalogue, entities and related entity data is submitted through a REST API. Entities can also be modified by creating relationships and editing their Custom Attributes via API.
This page will guide you through creating a key for the Data Catalogue as well as provide a Powershell Script for integrating with the Data Catalogue API.
The API is versioned and the Data Catalogue uses V1.
Creating a Data Catalogue API Key
An API Key with the Data Catalogue scope can easily be created from the API Keys page under the “Manage” section under the Settings Cog.
For an API Key to work with the Data Catalogue endpoints, you must attach the Data Catalogue to the key.
Please ensure you save the generated API Key in a secure place as they can only be revealed once.
Using the Swagger API Explorer
In order to externally add in entities and relationships to the Data Catalogue, the Swagger API Explorer will expose a number of endpoints that will allow you to create an entity and add data to this entity, such as its Entity Type and Custom Attributes. Below are the endpoints that are available in the API Explorer.
First click the ‘Open API Explorer’ button.
Provide the newly generated API Key into the API Key field at the top right hand corner.
Click on Show/Hide to explore all the exposed Data Catalogue endpoints. The endpoints are executable in your browser and includes sample request bodies for certain operations (such as entity creation and adding an Entity Type and Custom Attribute), just click on Expand Operations, fill out any required fields, select the Response Content Type, and then click on ‘Try it out!‘.
Use tooling such as Quicktype to generate class definitions based off the provided JSON schema.
Powershell Script for the API
The provided Powershell script includes functions for integrating with the Data Catalogue API, as well as an example of how to create two entities in the Website entity type that are connected with a relationship between the two entities.
# Provide an API key with Data Catalogue Permissions
$ApiKey = "Your API Key here";
# Provide the Loome Publish host url (for example https://sampleloomepublish.com/)
$URI = "Your Loome Publish Uri";
# Cleanup input variables
$URI = $URI.Trim("/");
# Set the standard headers for all requests to the Data Catalogue
$ApiRequestHeaders = @{
"Accept" = "application/json";
"ApiKey" = $ApiKey;
"Content-Type" = "application/json";
};
# Returns a properly formatted request URI
function Get-FullApiPath($RelPath) {
return $URI + "/api/external/v1/" + $RelPath.Trim("/")
}
# Get the entity types available in the Data Catalogue.
function Get-EntityTypes() {
return (Invoke-WebRequest -Method Get -Headers $ApiRequestHeaders -Uri (Get-FullApiPath -RelPath "entity-types")).Content | ConvertFrom-Json;
}
# Get the entities from the Data Catalogue.
function Get-Entities() {
return (Invoke-WebRequest -Method Get -Headers $ApiRequestHeaders -Uri (Get-FullApiPath -RelPath "entities")).Content | ConvertFrom-Json;
}
# Get the custom attribute types from the Data Catalogue.
function Get-CustomAttributeTypes() {
return (Invoke-WebRequest -Method Get -Headers $ApiRequestHeaders -Uri (Get-FullApiPath -RelPath "custom-attributes")).Content | ConvertFrom-Json;
}
# Add a collection of entities to the Data Catalogue.
function Add-Entities($Entities) {
$EntityCreationResponse = Invoke-WebRequest -Method Post -Uri (Get-FullApiPath -RelPath "entities") -Headers $ApiRequestHeaders -Body (ConvertTo-Json $Entities -Depth 100);
Write-Host $EntityCreationResponse.Content;
return ConvertFrom-Json -InputObject $EntityCreationResponse.Content;
}
# Update a collection of entities in the Data Catalogue.
function Update-Entities($Entities) {
Invoke-WebRequest -Method Put -Uri (Get-FullApiPath -RelPath "entities") -Headers $ApiRequestHeaders -Body (ConvertTo-Json $Entities) | Out-Null;
}
# Delete a set of entities from the Data Catalogue based on their IDs.
function Remove-Entities($EntityIds) {
Invoke-WebRequest -Method Delete -Uri (Get-FullApiPath -RelPath "entities") -Headers $ApiRequestHeaders -Body (ConvertTo-Json $EntityIds) | Out-Null;
}
# Get an example entity object from the Data Catalogue, based on an entity type ID.
function Get-EntityTypeExample($EntityTypeId) {
$Response = Invoke-WebRequest -Method Get -Uri (Get-FullApiPath -RelPath "entity-types/$EntityTypeId/example") -Headers $ApiRequestHeaders;
return ConvertFrom-Json -InputObject $Response.Content;
}
$EntityTypeId = 70 # 'Website' entity type
$ParentSite = Get-EntityTypeExample -EntityTypeId $EntityTypeId; # Get an example website entity for the parent site.
$ChildSite = Get-EntityTypeExample -EntityTypeId $EntityTypeId; # Get an example website entity for the child site.
$ParentSite.name = "BizData"; # Provide a parent site name
$ChildSite.name = "Loome Software"; # Provide a child site name
$CreatedEntities = Add-Entities -Entities $ParentSite, $ChildSite; # Add the Entities
$EntitiesWithRelationships = $CreatedEntities | Select-Object *, "Sources", "Targets" # Add a sources and targets
$EntitiesWithRelationShips | ForEach-Object { $_.Sources = @(); $_.Targets = @(); }; # Setup empty arrays
$EntitiesWithRelationships[1].targets = @($EntitiesWithRelationships[0].id); # Provide a relationship
Update-Entities -Entities $EntitiesWithRelationships # Update Entities with the relationships