Welcome to the Data360 Govern REST API documentation.
The information in this section is provided in conjunction with the Swagger API documentation, where you can test out queries and see details of specific endpoints. You can access the Swagger documentation from the application by navigating to
.The Data360 Govern API allows you to access the application via third party applications, and enables you to easily integrate with Data360 Analyze and Data360 DQ+.
Versioning
The v1 API has been deprecated and will not be supported in a future release. Please use the v2 API where possible.
The application is secured via SNI (Server Name Indication). You must be using SNI version 7.18.1 or above, and at least TLS 1.0.
Authentication
To authenticate, you must provide your API credentials in the request header in the following format:
<API Key>;<API Secret>
Obtaining API credentials
Data360 Govern generates an API Key and an API Secret for each user.
You can obtain your API credentials as follows:
- Sign in to Data360 Govern.
- From the Profile menu at the top right of the screen, select API Key.
- Copy the value from the Api Key field and save it outside of the application.
- Copy the value from the Api Secret field and save it outside of the application. You will need to use these values to access the API.
In some cases, for example when integrating with Data360 Analyze, the API credentials that are used to connect may be the credentials for a service account that was created specifically for your integration. In this case, please contact your Precisely representative for more information.
Making a request
A request is made up of the following pieces of information:
- Request headers - Provide information to the client and server, including authentication credentials and accepted data formats.
- Method - Defines the type of request to be made (GET, POST, PUT and DELETE).
- Endpoint - Indicates how you access the resource.
- Body - A body is sent with POST, PUT and DELETE requests and contains information for the server to act on, for example object name, fields and field values.
Additionally, some endpoints also carry optional or mandatory parameters which are used to further tailor the API response.
Request headers
Header key | Description |
---|---|
Authorization |
Specifies the authentication credentials:
|
Content-Type |
Specifies the format of the data:
|
Accept |
Specifies the data format that is acceptable for the response:
|
You can also use a workflow token in the Value field of the header. See Creating a workflow that calls an external API > Step 2 - Configure the HTTP Request activity, for more details.
Methods and endpoints
Endpoints indicate how you access the resource, and the HTTP request method defines the type of request to be made.
The Data360 Govern API uses the following standard methods to make requests:
Method | Action |
---|---|
GET | Retrieves resources |
POST | Creates resources |
PUT |
Updates existing resources |
DELETE | Deletes resources |
In some cases, PUT requests can also be used to create resources. For example, the PUT api/v2/fields
endpoint can be used to add or update field types. For the details of a specific PUT request, see the endpoint summary details in Swagger, for example:
Each resource has a variety of related endpoints. The endpoint shows the end path of a resource URL, and the base path is common to all endpoints, for example:
https://example.data3sixty.com/api/v2/assets/types
Request body
In the Swagger UI, each API method that requires a request body includes an example template which you can use as a starting point and then modify to meet the needs of your request.
For example, the POST /api/v2/metrics/results
endpoint has a mandatory request body which requires you to reference an asset UID and a metric asset UID:
[
{
"AssetUid": "b1c4f830-c71c-4f95-909d-a1d67ca5361c",
"MetricAssetUid": "d06f201c-4241-4102-8d68-07d4fb37dfc1",
"EffectiveDate": "2019-05-08T08:51:56.737Z",
"Result": true
}
]
In Swagger, the request body is displayed as follows:
Click the example template on the right of the screen to populate the model parameter on the left, then enter actual UID values to replace the placeholder text (00000000-0000-0000-0000-000000000000
).
You must include any required fields in the request body, for example when creating a new asset via a POST request. Optional fields can be deleted if there is no value to send.
For some requests, for example, batch requests for large amounts of data, you can include an optional parameter to track success or failure of the asset addition or update.
Parameters
Some endpoints also carry optional or mandatory parameters which are used to further tailor the API response.
Parameter type | Description | Example |
---|---|---|
Path | Parameters that are included within the path of the endpoint, usually within curly braces. |
The GET
|
Query | Parameters that are included in the query
string of an endpoint, following a
'? ' character. |
The GET
|
You can find details of specific parameters on the Swagger API documentation page.
Example request
The example API requests in this section of the help use Curl syntax to show all of the information that is required, including request headers, methods, endpoints, and data, as well as any mandatory and optional parameters:
curl -X GET --header 'Accept: application/json' --header 'Authorization: key;secret' 'https://example.data3sixty.com/api/v2/assets/types'
Curl provides a library and command-line tool for transferring data to servers using various standard protocols such as HTTPS.
The following example shows the header information for the same request for use when connecting to the Data360 Govern API via an API client:
GET https://example.data3sixty.com/api/v2/assets/types HTTP/1.1
Authorization: <API Key>;<API Secret>
Content-Type: application/json
Accept: application/json
Evaluating the response
Response codes
HTTP status code | Description | Troubleshooting |
---|---|---|
200 |
Indicates success. |
N/A |
400 |
Indicates an error due to an invalid request. |
Check that you have correctly formatted the identifier (UID) in your request. |
401 | Indicates an authentication error. |
Check that your request header includes the required authentication credentials. If you are still having trouble, it may be that you do not have the required permission to view or edit the resource based on the responsibilities that have been assigned to you in the application. |
403 | Indicates an 'access denied' error. | It may be that you do not have the required permission to view or edit the resource based on the responsibilities that have been assigned to you in the application. |
404 | Indicates that the requested resource was not found. | Check that you have correctly formatted the identifier (UID) in your request. |
406 | Indicates that the request does not contain the required parameter type or fields. | Check that you have included all required parameter types and fields. |
409 | Indicates that the requested resource already exists. | N/A |
500 | Indicates that an unknown error occurred while processing the request. | N/A |
Example response
HTTP/1.1 200 OK
"content-length": "2",
"content-type": "application/json; charset=utf-8"
[
{
"uid": "85315000-c77f-4898-84db-f4872cbd2dc0",
"Name": "Bloomberg",
"Description": "Metadata via the Bloomberg Fields CSV file and other Bloomberg sources.",
"Class": {
"ID": 3,
"Name": "Technical Asset",
"Description": "Technical assets."
},
"Path": "Bloomberg"
},
{
"uid": "88e6e59c-0cd8-49a9-a4f4-059b7172ddee",
"Name": "Business Calendar",
"Class": {
"ID": 4,
"Name": "Technical Asset",
"Description": "Technical assets."
},
"Path": "Business Calendar"
}
]
Common use cases
The Data360 Govern API enables you to obtain information about the assets in your data governance application.
Typical use cases include:
- Obtaining information about existing assets in your data governance system, including relationship and ownership details.
- Adding technical metadata from external data sources to provide context to your business assets.
- Applying scoring to your data governance assets (see Using the API to apply scoring to your assets).
- Promoting technical assets to your business glossary.
Hints and tips
Hint | Description |
---|---|
Endpoints for batch processing |
When working with a large number of items, it is recommended that you use the 'batch' endpoints. Where there is a 'batch' endpoint, the 'non-batch' equivalent often has a 250 item limit. The 'batch' endpoints are intended for a greater number of items as they store the item list for asynchronous or batch processing. For example, you can use the following endpoints to remove a set of assets based on the specified asset type unique identifier. The first is intended for a smaller number of items, and the second is intended for processing a greater number of items:
Note: It is recommended that you do not use the
Swagger UI for large requests. For handling
larger requests, it is recommended that you
use an alternative API client.
Note: Each environment is limited to two batch
requests at a time.
Note: The order of execution of batch API calls
is not guaranteed to be the order that the
jobs were submitted. For example, if you
submit ten batch jobs within 30 seconds, the
jobs will not necessarily execute in the
order that they were submitted.
|
Page size |
There is no maximum page size. However, it is
recommended that you restrict the page size
according to the size of your query. For
example, when using the GET
You can use the |
JSON properties |
Due to the way in which the JSON serializer handles data, if the value is null, there is no guarantee that the property will be displayed. Similarly, the order of the properties that are returned is not always the same. |
X-HTTP-Method-Override header |
To avoid doing a POST request with a body,
you can use |
Asset key fields |
When you execute an update (a PUT request), the API looks up all key field values, using the supplied asset UID. You will receive an error if the specified asset type has a key field defined and there are assets which have a NULL value for this field. |
Asset links |
Any asset can be accessed at the following
link, where
For example:
You can access the asset type list page for
business assets, technical assets, model
assets or rule assets at the following link,
where
For example:
|