Monetization Service - API
Overview
The Monetization Service API provides a GraphQL API for the management and publishing of all entities. The Monetization API is also integrated into the message-bus to process messages from other services.
GraphQL API
The Monetization API is exposed to management applications. This API provides an interface to the full entity graph stored by the Monetization Service with all relations between the entities to query, filter, and sort. These endpoints are used by the GUI workflows, but can also be used for integration purposes.
GraphQL Queries exclusively access the Monetization database for data retrieval.
GraphQL Mutations access the Monetization database to write and retrieve data. Some Mutations have additional effects such as publishing messages to RabbitMQ. These additional effects are detailed in Subscription Plan Publication and Claim Set Publication.
API documentation and an interactive query development environment are hosted by the Monetization Service using GraphiQL.
Messaging
While the GraphQL API offers synchronous queries and mutations, the messaging interface is based on the Mosaic message-bus implementation for asynchronous communication.
Synchronize Claim Definitions
The Monetization solution offers commands to update claim definitions.
Claim Definitions should be defined by an external service (usually an Entitlement Service) and should be synchronized to Monetization Service by a command message. Claim Definitions must always be synchronized with the Monetization Service if they change.
| Command | Purpose | Parameters | JSON Schema source |
|---|---|---|---|
|
Configure claims |
Claim definition schema. |
|
|
Published on successfully updating claims. |
|
|
|
Published if claims update results in an error. |
|
Upon receiving a synchronize-claim-definitions-start-command, the following operations are taken:
-
Validate the message payload against the defined schema.
-
If validation was successful: Insert, update and delete Claim Definition Groups and Claim Definitions in the Monetization Service database.
-
Publish a
synchronize-claim-definitions-finished-eventorsynchronize-claim-definitions-failed-eventto indicate success or failure. In the case of a failed event, any changes will have been rolled back.
Updating Claim Definitions is not generally a destructive process. Synchronizing claim sets which are not changed will have no effect.
-
Changing Claim Definition titles.
-
Changing Claim Definition Group titles.
-
Adding Claim Definitions to a group.
-
Deleting Claim Definitions.
-
Changing Claim Definitions keys.
If any changes affect a published Claim Set, the publication status of the Claim Set will become 'CHANGED'.
Subscription Plan Publication
Subscription plan publication is implemented by 2 GraphQL endpoints:
-
Validation Query:
validateSubscriptionPlan -
Publish Mutation:
publishSubscriptionPlan
If there are no validation errors, a payloadHash property is included in the Validation Query response. This payloadHash must be included as a parameter to the Publish Mutation to ensure that the published event does not include any changes made since validation.
Event schema
A Subscription Plan Published Event is published when a new or existing Claim Set is published. The Subscription Plan may not be changed since last publication.
| Event | Parameters | JSON Schema source |
|---|---|---|
|
Subscription plan including Payment Plans and references to assigned Claim Sets and Bundles. |
|
subscription-plan-published-event payload{
"id": "21029e04-2462-4e38-af6e-a395274f7418",
"title": "Premium",
"is_active": true,
"description": "Watch all movies and all TV shows from our catalog.",
"provider_configs": [{
"payment_provider_key": "PAYPAL",
"external_id": "PROD-premium"
}],
"payment_plans": [{
"id": "80190b19-d7e2-4d2c-ad73-4175aba7f509",
"title": "Monthly",
"description": "Pay monthly to watch all movies and all TV shows from our catalog.",
"is_active": true,
"period_unit": "MONTH",
"period_quantity": 1,
"provider_configs": [{
"payment_provider_key": "PAYPAL",
"external_id": "P-DHOAS7DJIC96DSAUHDISHAU65"
}],
"prices": [{
"country": "EE",
"currency": "EUR",
"price": 9.99
}, {
"country": "DE",
"currency": "EUR",
"price": 9.99
}]
}],
"claim_set_keys": ["PREMIUM_CONTENT"],
"images": [{
"width": 1300,
"height": 1600,
"type": "COVER",
"path": "/transform/0-0/LWdMpMnGHnh98aJ5vGE14G.jpg"
}]
}Claim Set Publication
Claim Set publication is implemented by 2 GraphQL endpoints.
-
Validation Query:
validateClaimSet -
Publish Mutation:
publishClaimSet
If there are no validation errors, a payloadHash property is included in the Validation Query response. This payloadHash must be included as a parameter to the Publish Mutation to ensure that the published event does not include any changes made since validation.
Event schema
A Claim Set Published Event is published when a new or existing Claim Set is published. The Claim Set may not be changed since last publication.
| Event | Parameters | JSON Schema source |
|---|---|---|
|
Claim Set including its claims. |
|
claim-set-published-event payload{
"key": "PREMIUM_CONTENT",
"title": "Premium Content",
"description": "Access to all movies and all TV shows.",
"claims": ["ENTITY_TYPE_MOVIES","ENTITY_TYPE_TV_SHOWS"]
}Claim Set Unpublish
A Claim Set Unpublished Event is published when a Claim Set is unpublished. This indicates that the Claim Set should no longer be used. The Claim Set may be deleted or re-published in future.
| Event | Parameters | JSON Schema source |
|---|---|---|
|
Claim Set key to be unpublished. |
|
claim-set-unpublished-event payload{
"key": "PREMIUM_CONTENT"
}