Login

Mosaic products documentation: Concepts, API Reference, Technical articles, How-to, Downloads and tools

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.

monetization api component
Figure 1. Monetization API component diagram

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.

GraphiQL URL for documentation and interactive query development

https://monetization.service.eu.axinom.net/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

monetization-service-enable-start-command

Enable service

tenant_id, environment_id

Standard Mosaic event

monetization-service-disable-start-command

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:

  1. Send a workflows-enable-start-command to the Micro Frontend service to enable workflows for the service.

  2. Send a declare-images-types-command to the Image Service to enable images of type Subscription Plan Cover to be uploaded.

  3. Publish a monetization-service-enable-finished-event or monetization-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:

  1. Remove all environment data. All Subscription Plans, Claim Sets and relations are permanently deleted.

  2. Publish a monetization-service-disable-finished-event or monetization-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

synchronize-payment-providers-start-command

Configure payment providers

List of payment providers.

@mosaic-messages

Upon receiving a synchronize-payment-providers-start-command, the following operations are taken:

  • Insert, update and delete Payment Providers in the Monetization Service database.

    1. Publish a synchronize-payment-providers-finished-event or synchronize-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

synchronize-claim-definitions-start-command

Configure claims

Claim definition schema.

@mosaic-messages

synchronize-claim-definitions-finished-event

Published on successfully updating claims.

@mosaic-messages

synchronize-claim-definitions-failed-event

Published if claims update results in an error.

@mosaic-messages

Upon receiving a synchronize-claim-definitions-start-command, the following operations are taken:

  1. Validate the message payload against the defined schema.

  2. If validation was successful: Insert, update and delete Claim Definition Groups and Claim Definitions in the Monetization Service database.

  3. Publish a synchronize-claim-definitions-finished-event or synchronize-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.

Operations which will not affect Claim Sets:

  • Changing Claim Definition titles.

  • Changing Claim Definition Group titles.

  • Adding Claim Definitions to a group.

Operations which can affect existing Claim Sets:

  • 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:

  1. Validation Query: validateSubscriptionPlan

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

Management userManagement userMonetization WorkflowsMonetization WorkflowsMonetization APIMonetization APIImage ServiceImage ServiceMessage BusMessage BusSubscription PlanPublishingQuery:validateSubscriptionPlanGet metadata forSubscription PlanValidateSubscription Plan metadataRequest image metadataSend image metadataalt[No validation errors]Generate payload hashValidation response witherror list / payload hashalt[No validation errors]Confirm PublishMutation:publishSubscriptionPlan(including payload hash)Request image metadataSend image metadataGet metadata for Subscription Planand all child entitiesGenerate payloadalt[Generated payload matches payload hash]Set publication_state of Subscription Planand all child entities to PUBLISHEDPublish subscription-plan-published-eventPublication response
Figure 2. Sequence diagram for Subscription Plan publishing

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-published-event

Subscription plan including Payment Plans and references to assigned Claim Sets and Bundles.

@mosaic-messages
Example 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.

  1. Validation Query: validateClaimSet

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

Management userManagement userMonetization WorkflowsMonetization WorkflowsMonetization APIMonetization APIImage ServiceImage ServiceMessage BusMessage BusClaim SetPublishingQuery:validateClaimSetGet metadata forClaim SetValidateClaim Set metadataalt[No validation errors]Generate payload hashValidation response witherror list / payload hashalt[No validation errors]Confirm PublishMutation:publishClaimSet(including payload hash)Get metadata for Claim SetGenerate payloadalt[Generated payload matches payload hash]Set publication_state of Claim Set to PUBLISHEDPublish claim-set-published-eventPublication response
Figure 3. Sequence diagram for Claim Set publishing

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-published-event

Claim Set including its claims.

@mosaic-messages
Example 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-unpublished-event

Claim Set key to be unpublished.

@mosaic-messages
Example claim-set-unpublished-event payload
{
    "key": "PREMIUM_CONTENT"
}

Axinom uses cookies for analytics and personalized content. By continuing to browse this site, you agree to this use. Learn more