API Reference > Define settings for data collections > Usage types

Usage types

A usage type defines the contexts within which an individual can use data. Stakeholders can utilize usage types to specify the intended use of their data collections. Data Users can utilize usage types to cite their intention when they order a collection.

Create usage type

Use REST APIs to create usage types in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/usageContext
Method	POST

Request

The following table describes the parameters that you enter in the body of the API payload:

Parameter	Description	Additional Information
refId	Optional. Enter a reference identifier for the usage type.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the object. The reference identifier that Data Marketplace automatically generates contains a prefix. The Administrator can specify the prefix of the automatically generated reference identifier in Metadata Command Center. If you want to specify a reference identifier, ensure that you enter a unique value. Ensure that you don't use the prefix value that is configured in Metadata Command Center.
name	Required. Enter a name for the usage type.	Ensure that you enter a unique value. Data Marketplace doesn't consider the letter case when it verifies the uniqueness of the name parameter's value. For example, if you try to name a usage type as "Sales Analytics" while a usage type called "Sales analytics" already exists, the API call fails.
description	Required. Enter a description for the usage type.	-
color	Required. Specify a color indicator for the usage type. Assigning a unique color indicator allows Data Marketplace users to identify a usage type easily.	Enter the hexadecimal value that represents the color that you want to use.
status	Required. Specify a status for the usage type. The status determines whether a usage type is available to be added to a data collection or to be selectable on an order.	Enter one of the following values: - To make the usage type available, enter ACTIVE . - To make the usage type unavailable, enter INACTIVE .

Example request

The following example shows how you can use an API to create an usage type:

{
"items": [
{
"refId": "UType314",
"name": "Retail-Use",
"description": "This is for standard retail operations.",
"color": "#aAbe2A",
"status": "INACTIVE"
}
]
}

Response

When you pass the API payload in the REST client, the client displays a response for the parameter values that you have entered.

The following example shows the response of an API call to create an usage type:

{
"result":
{
"processingTime":2023,
"objects":
[
{
"index": 1,
"id":"964dfd5f-0add-4749-9ed8-79016a8e9f69",
"refId":"UType314",
"name":"Retail-Use"
}
]
}
}

The following table describes the parameters of each usage type that is created:

Parameter	Description
index	The position of the usage type in the objects JSON array. This value does not impact how the usage type is used by a Data Marketplace user.
id	System generated unique identifier of the usage type.
refId	Reference identifier of the usage type.
name	Name of the usage type.

Retrieve usage type

Use REST APIs to retrieve the details of usage types in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/usageContext
Method	GET

Note: Before you call this API, consider the following:

•If you use an Application Integration system service action to invoke this API, you can call a maximum of 100 APIs per minute.
•If you use JWT authentication to invoke this API, you can call a maximum of 120 APIs per minute and 10,000 APIs per day.

For more information, see How to call a Data Marketplace API.

Request

The following table describes the parameters that you enter in the request query:

Parameter	Description	Additional Information
ids	Optional. Enter the system generated unique identifier of a usage type.	To enter more than one value, use the following format: ids=<value1>&ids=<value2>
search	Optional. Enter the search term that you want to use to find a usage type.	Ensure that the search term that you enter don't contain an asterisk (*).
fields	Optional. Enter the fields on which the search term applies. The terms that you entered in the search field parameter are used to search the fields that you specify here.	Enter the following values: - NAME - DESCRIPTION
createdDateFrom	Optional. To find usage types that were created between a date range, enter the initial date when the usage types were created.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the createdDateFrom parameter, ensure that you also enter a value for the createdDateTo parameter.
createdDateTo	Optional. To find usage types that were created between a date range, enter the latest date when the usage types were created.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the createdDateTo parameter, ensure that you also enter a value for the createdDateFrom parameter.
modifiedDateFrom	Optional. To find usage types that were modified between a date range, enter the initial date when the usage types were modified.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the modifiedDateFrom parameter, ensure that you also enter a value for the modifiedDateTo parameter.
modifiedDateTo	Optional. To find usage types that were modified between a date range, enter the latest date when the usage types were modified.	To specify a date, use the YYYY-MM-DD format. The value that you specify is automatically converted and stored in the Coordinated Universal Time (UTC) time standard. If you have specified a value for the modifiedDateTo parameter, ensure that you also enter a value for the modifiedDateFrom parameter.
sortByField	Optional. Specify the parameters to sort the search results.	To sort the search results, enter one of the following values: - NAME - STATUS - CREATED_BY - CREATED_ON - MODIFIED_BY - MODIFIED_ON Default value is MODIFIED_ON.
sort	Optional. Set the sorting order of the search results.	You can sort the search results in the following order: - To sort the search results by ascending order, enter ASC. - To sort the search results by descending order, enter DESC. Default value is DESC.
status	Optional. Specify the status of the usage type. The status indicates whether a usage type is available to be added to a data collection or to be selectable on an order.	Enter one of the following values: - To find the usage types that are available, enter ACTIVE. - To find the usage types that aren't available, enter INACTIVE.
offset	Optional. Enter the starting index for the paginated results.	Default value is 0.
limit	Optional. Enter the maximum number of results.	Default value is 50. Maximum value is 100.

Note: The API has no payload.

Example request

The following example shows how you can use an API to retrieve an usage type:

https://{{CDMP_URL}}/api/v1/integration/usageContext?ids=c20c8fb4-1cb4-477f-8ff9-52908a3c01d3&search=abcd&fields=NAME&createdDateFrom=2022%2F01%2F01&createdDateTo=2022%2F07%2F22&modifiedDateTo=2022%2F02%2F01&modifiedDateFrom=2022%2F07%2F22&status=ACTIVE&sortByField=NAME&sort=ASC&offset=0&limit=20

Response

When you pass the API query parameters in the REST client, the client displays a response for the parameter values that you have entered.

The following example shows the response of an API call to retrieve an usage type:

{
"result":
{
"offset":0,
"limit":50,
"totalCount":1,
"objects":
[
{
"id":"964dfd5f-0add-4749-9ed8-79016a8e9f69",
"refId":"UType314",
"name": "Retail-Use",
"description": "This is for standard retail operations.",
"color": "#aAbe2A",
"status":"INACTIVE",
"createdBy":"f400dUqjPuaiJ9KBrzOhiB",
"createdOn":"2022-07-26T11:19:17.550Z",
"modifiedBy":"f400dUqjPuaiJ9KBrzOhiB",
"modifiedOn":"2022-07-26T11:19:17.550Z"
}
]
}
}

The following table describes the parameters of each usage type that is retrieved:

Parameter	Description
offset	Starting index for the paginated results.
limit	Maximum number of results.
totalCount	Number of usage types retrieved.
id	System generated unique identifier of the usage type.
refId	Reference identifier of the usage type.
name	Name of the usage type.
description	Description of the usage type.
color	A hexadecimal value that represents the color indicator of the usage type.
status	The status indicates whether a usage type is available to be added to a data collection or to be selectable on an order. A usage type can have one of the following values: - ACTIVE. The usage type is available. - INACTIVE. The usage type is available.
createdBy	System generated unique identifier of the user account that created the usage type.
createdOn	Date when the usage type was created.
modifiedBy	System generated unique identifier of the latest user account that modified the usage type.
modifiedOn	Latest date when the usage type was modified.

Modify usage type

Use REST APIs to modify usage types in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/usageContext
Method	PUT

Request

The following table describes the parameters that you enter in the body of the API payload:

Parameter	Description	Additional Information
id	Required. Enter the system generated unique identifier of the usage type that you want to modify.	For more information about how you can use an API to get the unique identifier of a usage type, see Retrieve usage type.
refId	Optional. Enter a reference identifier for the usage type.	If you don't specify a reference identifier, Data Marketplace automatically assigns a unique value to the object. The reference identifier that Data Marketplace automatically generates contains a prefix. The Administrator can specify the prefix of the automatically generated reference identifier in Metadata Command Center. If you want to specify a reference identifier, ensure that you enter a unique value. Ensure that you don't use the prefix value that is configured in Metadata Command Center.
name	Required. Enter a name for the usage type.	Ensure that you enter a unique value. Data Marketplace doesn't consider the letter case when it verifies the uniqueness of the name parameter's value. For example, if you try to name a usage type as "Sales Analytics" while a usage type called "Sales analytics" already exists, the API call fails.
description	Required. Enter a description for the usage type.	-
color	Required. Specify a color indicator for the usage type. Assigning a unique color indicator allows Data Marketplace users to identify a usage type easily.	Enter the hexadecimal value that represents the color that you want to use.
status	Required. Specify a status for the usage type. The status determines whether a usage type is available to be added to a data collection or to be selectable on an order.	Enter one of the following values: - To make the usage type available, enter ACTIVE . - To make the usage type unavailable, enter INACTIVE .

Example request

The following example shows how you can use an API to modify an usage type:

{
"items": [
{
"id": "964dfd5f-0add-4749-9ed8-79016a8e9f69",
"refId": "UType314",
"name": "Retail-Use",
"description": "This is for standard retail operations.",
"status": "ACTIVE"
}
]
}

Response

When you pass the API payload in the REST client, the client displays a response for the parameter values that you have entered.

The following example shows the response of an API call to modify an usage type:

{
"result":
{
"processingTime":1286,
"objects":
[
{
"index": 1,
"id":"964dfd5f-0add-4749-9ed8-79016a8e9f69",
"refId":"UType314",
"name":"Retail-Use"
}
]
}
}

The following table describes the parameters of each usage type that is modified:

Parameter	Description
index	The position of the usage type in the objects JSON array. This value does not impact how the usage type is used by a Data Marketplace user.
id	System generated unique identifier of the usage type.
refId	Reference identifier of the usage type.
name	Name of the usage type.

Update the status of an usage type

Use REST APIs to enable or disable usage types in Data Marketplace.

Endpoint and method

The following table describes the connection properties for the API:

Property	Description
Endpoint	/api/v1/integration/usageContext/status
Method	PATCH

Request

The following table describes the parameters that you enter in the body of the API payload:

Parameter	Description	Additional Information
id	Required. Enter the system generated unique identifier of the usage type.	For more information about how you can use an API to get the system generated unique identifier of a usage type, see Retrieve usage type.
status	Required. Specify a status for the usage type. The status determines whether a usage type is available to be added to a data collection or to be selectable on an order.	Enter one of the following values: - To make the usage type available, enter ACTIVE . - To make the usage type unavailable, enter INACTIVE .

Example request

The following example shows how you can use an API to update the status of an usage type:

{
"items": [
{
"id": "bd1bcf0a-c05c-4a12-b5df-67215475cf25",
"status": "INACTIVE"
}
]
}

Response

When you pass the API payload in the REST client, the client displays a response for the parameter values that you have entered.

If you see the following response code, it means that the status of the usage type is updated successfully:

204 OK