DRM Rights Service API v1.0 1.0

DRM Rights Service API Specifications (Version 1.0)

Server

https://drm-qa.adara.com/drm/rights/v1.0

https://drm.adara.com/drm/rights/v1.0

Authentication

oauth2 oauth2

FlowClient Credentials

Token URL/core/v1.0/oauth/token

Fetch

POST

/fetch

fetch

Get the data permissions of eligible dp_ids found by DRM Rights Service for the data use case specified in the request body. The ids of request parameters are available to be looked up in DRM CloudSQL mysql server now and DRM UI in the future. NOTE: The fetch API should be called every time for obtaining the latest dpPermissions and a new delivery token for the data use case, previously obtained eligible dp_ids and delivery_token should not be cached on the caller's end to be reused for the multiple data generation of the same data use case.

Auth

Required Scopes:fetch:/drm/rights/v1.0/fetch

Request Body

The fetch request body contains the data use case parameters.

object	object
productId	string	[Required] Id of the Adara product that uses the data
dataTypes	array[string]	[Required] The ids of data types needed for this data use case. Note that at least one data type needs to be specified, otherwise, a bad request error will occur.
usageTypes	array[string]	[Required] The ids of data usage types involved in this data use case. Note that at least one usage type needs to be specified, otherwise, a bad request error will occur.
drmConsumers	object	A consumer of the output data of this data use case.
drmClients	array[string]	Client consumers of the data
drmVerticals	array[string]	Vertical consumers of the data
destinations	array[string]	[Required] The ids of destination platforms where the output data of the data use case will be delivered. Pass an empty list in this field to denote that the output data will be delivered to ALL destination platforms.
dataOrigins	array[string]	[Required] The ids of geographical region(s) where data providers' data is collected from. Pass an empty list in this field to denote that data collected from ALL geographical regions are needed for the data use case.
excludedDpIds	array[integer]	[optional] The data provider ids to be excluded from the data use case prior in advance and regardless of the eligibility. Note this field should not co-exist with expectedDpIds in the request, otherwise, a bad request error will occur.
fetchForDelivery	boolean	[optional] A flag to indicate whether this fetch request call is driven by an intended data generation and delivery. A delivery_token will be issued and returned in the response if this field is set to true. This field is set to false by default if it's not specified in the request.

POST /fetch

xxxxxxxxxx
 
curl --request POST \ --url 'https://drm-qa.adara.com/drm/rights/v1.0/fetch' \ --header 'Authorization: Bearer {token}' \ --data '{  "productId": "{string}",  "dataTypes": [    "{array[string]...}"  ],  "usageTypes": [    "{array[string]...}"  ],  "drmConsumers": {    "drmClients": [      "{array[string]...}"    ],    "drmVerticals": [      "{array[string]...}"    ]  },  "destinations": [    "{array[string]...}"  ],  "dataOrigins": [    "{array[string]...}"  ],  "excludedDpIds": [    "{array[integer]...}"  ],  "fetchForDelivery": "{boolean}"}'
Copy

Responses

200

A DpPermission list of eligible dp_ids will be returned if there are eligible dp_ids found for the given data use case. A delivery_token will also be issued if fetchForDelivery is set to true in the request body.

object	object
dpPermissions	array[object]	A list of data permission object of the eligible dp_ids to the data use case.
dpId	integer	The id of the data provider.
deliveryToken	string	The delivery_token obtained from the preceding Fetch request. It will be used by DRM to retrieve the information provided in the preceding fetch request for validating this data delivery and log the information of the output data for analytics and auditing purpose.

400

No eligible dp_id is found due to invalid parameters or values in the request. A short reason and detailed error message will be provided in the response.

401

Unauthorized error

404

No eligible dp_id is found regarding the given data use case. A short reason and detailed error message will be provided in the response.

Response

xxxxxxxxxx
 
{ "dpPermissions": [  {   "dpId": "{integer}"  } ], "deliveryToken": "{string}"}
Copy

Validate

POST

/validate

validate

Check with DRM rights service for getting the data delivery validated and approved before taking action to deliver the data. NOTE: the delivery_token must be paired with the output data generated for the delivery which this delivery_token was issued for. A delivery_token should neither be reused for delivering multiple data snapshots generated across time for the same data use case nor be used for the output data of other data use case.

Auth

Required Scopes:fetch:validate:/drm/rights/v1.0/validate

Request Body

The request body needs to contain the previously issued delivery_token and the required information.

object	object
deliveryToken	string	The delivery_token returned along with the dp_ids which are used for generating the output data in this delivery.
outputSize	integer	The size of the output data

POST /validate

xxxxxxxxxx
 
curl --request POST \ --url 'https://drm-qa.adara.com/drm/rights/v1.0/validate' \ --header 'Authorization: Bearer {token}' \ --data '{  "deliveryToken": "{string}",  "outputSize": "{integer}"}'
Copy

Responses

200

The data delivery is validated and approved. The "approved" will be set to true in the response.

object	object
deliveryApproved	boolean	True as the validation is passed and the data delivery is approved.

400

The data delivery is unapproved due to invalid parameters or values in the request. The "approved" will be set to false in the response and a short reason and detailed error message will be provided in the response.

404

The data delivery is unapproved due to a specific reason. The "approved" will be set to false in the response and a short reason and detailed error message will be provided in the response.

Response

xxxxxxxxxx
 
{ "deliveryApproved": "{boolean}"}
Copy