Getting Started

Getting Started with the Mindful APIs

About Mindful

The Mindful ecosystem is a platform for publishing content, advertisements, and reporting.

About the APIs

The Mindful APIs can be used to manage users, create and publish content, advertisements, collect reporting data, and more! GraphQL Playground can be used as a locally installed API client, or the GraphQL connection can be accessed programmatically in most languages with the use of a client. For more information about using GraphQL check out the docs.

You'll need access to one or more organizations within Mindful to use these APIs. If you don't yet have access, please reach out to an organization administrator.

If you have trouble connecting, please reach out to [e-mail] and we'd be happy to help you out!

Connecting

All Mindful GraphQL APIs can be accessed as a sub-path of the graphql.mindfulcms.com domain. For details on each API, please see the relevant description page.

See the Authentication section for detailed information about the available authentication methods for each API.

Architecture & Data Model

Data Model

In Mindful, there are two important terms that relate to the structure of data within the ecosystem: Entity Kinds, and Variant Forms.

An Entity Kind represents a discrete type of data record and is typically stored in a discrete collection within the Mindful database. Some Entity Kinds (such as an EmailAutomationConfig) do not have an individual collection, and are embedded within another Entity Kind.

Each Entity Kind can have one or more Variant Forms (although usually two or more) which allows for different fields and materialization rules for the variant. For example, the Advertising Creative Entity Kind has three Variant Forms: Native Website, Native Email, and Image.

Entity Kinds and Variant Forms are defined as part of the Entity Event Store's schema definitions. The Entity Event Store also contains rules for normalization and materialization of the entity. (and related entities too!)

Event Sourcing

Mindful follows an Event Sourcing architecture. Each action that is taken with a specific entity, including creation and any subsequent updates, are stored as a individual action record in the Entity Event Store. These actions include both dates and user attribution, along with the data properties that were modified.

Each time one of these actions is written, a normalization process happens that builds the now-current representation of the entity from all of the existing actions. A secondary process (materialization) follows that includes additional data from other models according to a set of software-defined rules.

Event Sourcing allows for changes to related entities (such as updating the name of an Email Channel) to cascade to every document that includes an embedded copy of it. This allows you to both query for fields that don't belong to the document directly (such as an Advertising Company id several levels removed from the Advertising Creative), and return data for related models that would previously have required multiple individual queries to resolve.

Tenancy

The Mindful platform allows for two levels of tenancy to segregate your data

• An Organization, which is typically analogous with a company or brand.

• A Workspace, which is typically a vertical or other logical separator within an organization.

Every organization starts with one workspace by default (aptly named default), and additional workspaces can be created as needed.

Relationships across Workspaces are not currently possible, so any data that needs to be interrelated (such as an Advertising Company and Website Channel) must be in the same workspace.

Users can belong to multiple Organizations and Workspaces. User management is not yet available within the Mindful UI, but changes can be made by reaching out to your organization administrator.