API documentation - Data360_Govern - Preview

Data360 Govern Help

Product type
Software
Portfolio
Verify
Product family
Data360
Product
Data360 Govern
Precisely Data Integrity Suite > Govern
Version
Preview
Language
English
Product name
Data360 Govern
Title
Data360 Govern Help
Copyright
2024
First publish date
2014

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 Administration > Integration > API.

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+.

API overview

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:

  1. Sign in to Data360 Govern.
  2. From the Profile menu at the top right of the screen, select API Key.
  3. Copy the value from the Api Key field and save it outside of the application.
  4. 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.
Note: If you do not have administrator access, you may need to contact your system administrator if the API Key option is not visible in your user profile menu.

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.

Note: The responsibilities that have been assigned to you in the application will still apply when you are accessing data via the API. Therefore, you may not have the required permission to view or edit an asset even if you have successfully authenticated.

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.

Note: The default format for requests and responses is JSON (application/json). Parameter names use camelCase.

Request headers

Header key Description
Authorization

Specifies the authentication credentials:

Authorization: <API Key>;<API Secret>

Content-Type

Specifies the format of the data:

Content-Type: application/json

Accept

Specifies the data format that is acceptable for the response:

Accept: application/json

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:

Swagger API documentation

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:

Request body

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 /api/v2/assets/fields/{assetTypeUid} endpoint includes a mandatory path parameter, for example:

https://example-igx.preview.data3sixty.com/api/v2/assets/fields/188f094b-fb02-4de3-8790-8c0d32d98e1a

Query Parameters that are included in the query string of an endpoint, following a '?' character.

The GET /api/v2/fields endpoint has a number of optional query parameters. In the following example, the Type and _pageSize parameters are used to indicate that the response should only include Boolean type fields and that the number of results per page should be restricted to 100:

https://example.data3sixty.com/api/v2/fields?Type=Boolean&_pageSize=100

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.

Note: On Windows, you must replace the single quotes with double quotes.

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"
	}
]
Tip: In this example, the first item includes a 'Description' property, but the 'Description' property is not returned in the second item. In many cases, if there are custom fields on an asset, the field name and value may only be displayed in the response if the field has been populated. Note that this behavior is not affected by the Show if Empty field configuration in the application.

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:

  • DELETE /api/v2/assets/{assetTypeUid} - Use this endpoint if you want to process under 250 items and need immediate results.
  • DELETE /api/v2/assets/batch/{assetTypeUid} - Use this endpoint when 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 /api/v2/assets/{assetTypeUid} endpoint, it is recommended that you restrict the page size to 1000 or less, according to the amount of content that you are calling.

You can use the _pageSize parameter to restrict the number of results that are returned per page. The default value is 200.

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 X-HTTP-Method-Override: DELETE in the request header. For example, when deleting relationships in Data360 Govern via a connector.

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 <environment> is replaced with your Data360 host and <asset uid> is replaced with the UID value of an asset:

https://<environment>.data3sixty.com/asset/<asset uid>

For example:

https://example.data3sixty.com/asset/5f2692c7-6d64-4e23-9a11-faa69a7f35de

You can access the asset type list page for business assets, technical assets, model assets or rule assets at the following link, where <environment> is replaced with your Data360 host and <asset type uid> is replaced with the UID value of an asset type:

https://<environment>.data3sixty.com/assets/<asset type uid>

For example:

https://example.data3sixty.com/assets/188f094b-fb02-4de3-8790-8c0d32d98e1a