Monetization Service - API
Overview
Monetization Service API provides a GraphQL API for management and publishing of all entities. Monetization API also implements command handlers for processing of 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.
Setup Command Handlers
Monetization Service implements commands to enable / disable the service for a given environment. These commands are used for integration with the Mosaic Admin interface, and are not intended to be integrated directly by other services.
Command | Purpose | Parameters | Comment |
---|---|---|---|
|
Enable service |
tenant_id, environment_id |
Standard Mosaic event |
|
Disable service |
tenant_id, environment_id |
Standard Mosaic event |
The payload of all commands is defined using a JSON schema.
Enable Start Command Handler
Upon receiving a monetization-service-enable-start-command
, the following operations are taken:
-
Send a
workflows-enable-start-command
to the Micro Frontend service to enable workflows for the service. -
Send a
declare-images-types-command
to the Image Service to enable images of typeSubscription Plan Cover
to be uploaded. -
Publish a
monetization-service-enable-finished-event
ormonetization-service-enable-failed-event
to indicate success or failure.
Disable Start Command Handler
Upon receiving a monetization-service-disable-start-command
, the following operations are taken:
-
Remove all environment data. All Subscription Plans, Claim Sets and relations are permanently deleted.
-
Publish a
monetization-service-disable-finished-event
ormonetization-service-disable-failed-event
to indicate success or failure.
Synchronize Payment Providers Command Handler
Monetization Service implements a command handler to update payment providers. This command is used for integration with other Mosaic managed services and should not be integrated directly by any other service.
Command | Purpose | Parameters | JSON Schema source |
---|---|---|---|
|
Configure payment providers |
List of payment providers. |
|
Upon receiving a synchronize-payment-providers-start-command
, the following operations are taken:
-
Insert, update and delete Payment Providers in the Monetization Service database.
-
Publish a
synchronize-payment-providers-finished-event
orsynchronize-payment-providers-failed-event
to indicate success or failure. In the case of a failed event, any changes will have been rolled back.
-
Synchronize Claim Definitions Command Handler
Monetization Service implements a command handler to update claim definitions.
Claim Definitions should be defined by an external service (usually Entitlement Service) and synchronized to Monetization Service by command. It is expected that Claim Definitions are defined statically in code, but it is also possible for the full list to be generated dynamically, e.g. based on catalog metadata. In either case Claim Definitions must be synchronized with Monetization Service on 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-event
orsynchronize-claim-definitions-failed-event
to 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"
}