Integrations

Once you’ve created a Uni, the next step is to hook it up to the rest of your application. Vendia provides a large array of options for integrating your Uni with other cloud vendor services, APIs from any vendor, and with your web and mobile clients.

Web, Mobile, and API-based Access

Every Vendia Uni comes with built-in support for API-based web, mobile, and cloud integration. Vendia offers a GraphQL-based, HTTPS protocol API that supports your custom data model with queries and updates (“mutations” in GraphQL parlance).

The URL required to interact with this service is included in the resources returned from share get --uni <uni_name>, named httpsUrl.

To learn how to create an API Key, see our Node Authentication documentation.

share get --uni your-uni-name.unis.vendia.net
Getting your-uni-name.unis.vendia.net info...
┌─────────────────────┐
│   Uni Information   │
└─────────────────────┘
Uni Name:    your-uni-name.unis.vendia.net
Uni Status:  RUNNING
Node Count:  1
Node Info:
└─ ⬢ Node1
   ├─ name: Node1
   ├─ status: RUNNING
   └─ resources:
      ├─ graphqlApi
      │  ├─ httpsUrl https://abc123.execute-api.us-east-2.amazonaws.com/graphql/
      │  └─ websocketUrl wss://xyz345.execute-api.us-east-2.amazonaws.com/graphql
...

A simple example of using this to list a top-level, array-based data type in your model:

curl -XPOST <httpsUrl> \
    -H "Content-Type:application/graphql" \
    -H "Authorization:<apiKey>" \
    -d "{\"query\": \"query q {list_InventoryItems{_InventoryItems{name sku warehouse availableInventory}}}\"}"

Inbound Service Connectors

Vendia Share supports several additional inbound (“ingress”) options beyond GraphQL mutations:

Lambda functions and Amazon EventBridge. You can easily use AWS Lambda functions to convert any of the dozens of AWS-provided events into GraphQL mutations, including events from S3, Aurora, and many other AWS services into transactions and then submit them to the Vendia-provided SQS queue for processing.
SQS queues. Vendia automatically creates an inbound SQS queue to hold pending transactions. Vendia recommends using the GraphQL endpoint when possible because it is often easier and adds a layer of type safety; however, submitting transactions directly to SQS is supported.
SNS topics. You can connect an SNS topic to the Vendia-provided SQS queue for automatic ingress via SNS.

Outbound Service Connectors

When data in a Uni is modified, an update is made to the ledger to capture this information, but being able to react to what’s happening within your uni’s node(s) is a key piece of leveraging the power of Vendia Share. In order to accomplish this, each node can be configured to emit notifications upon success and failure when processing mutations.

Block Notification Flow

Block Notifications

When a given block has been committed to both the ledger or world state, your node will emit a notification consisting of a summary of the transactions included within said block.

Let’s assume you have configured an output integration. When a new block is created, your integration receives a notification.

{
  "blockId": "000000000000123",
  "blockHash": "block_hash",
  "mutations": [{ "_id": "transaction_Id", "_owner": "NodeOwner" }],
  "part": 1,
  "totalParts": 1
}

Once your integration receives a notification that a block has been created, the integration must then query the block. Below is a sample query that can be used to surface information about the mutation used to create the block.

query q {
  getVendia_Block(id: "000000000000123") {
    previousBlockId
    blockHash
    previousBlockHash
    commitTime
    transactions {
      _id
      _owner
      submissionTime
      mutations
    }
  }
}

This sample query will return relevant information about mutations recorded in the block.

{
  "data": {
    "getVendia_Block": {
      "previousBlockId": "000000000000123",
      "blockHash": "97d85748a39afc104573bf09f69fa388a5e9c6e922b9816508c8ef3ab75dfa38",
      "previousBlockHash": "518d1cc60efc14645f4dd54805ab7a78ef90bd06b3e1280c2d8c111c70322cc1",
      "commitTime": "2021-11-12T16:42:58.127872+00:00",
      "transactions": [
        {
          "_id": "transaction_Id",
          "_owner": "shipper",
          "submissionTime": "2021-11-12T16:42:50.691102+00:00",
          "mutations": [
            "updateSelf_Shipment(id:\"017d1206-7881-4279-995a-e4176d8f223a\",input: {delivered: true, lastUpdated: \"2020-12-02T14:10:02Z\", location: [47.3741, -122.031]}){error}"
          ]
        }
      ]
    }
  }
}

Based upon the contents of the block - the mutations in the list of transactions or perhaps the _owner - you can take action. What kind of action? Perhaps you need to instruct a Enterprise Resource Planning (ERP) application to release funds when a shipment is received in good order. Maybe you need to make a post to social media that an event has been scheduled by a partner. There is really no limit to what your integration can do.

Dead-Letter Notifications

When a given block is not approved by consensus, each transaction in the block is not applied.

When using either NODE_COMMITTED (default) or ASYNC sync mode, dead-letter notifications are the only way to be notified of transactions that fail to apply and will not be reflected within either the ledger or world state.

A dead-letter notification sent by a node will contain the following fields:

field name	description
`transactionId`	The ID of the transaction that failed to apply.
`mutation`	The raw form of the mutation within the transaction requiring attention.
`owner`	The name of the node that submitted the mutation.
`submissionTime`	The timestamp when the mutation was submitted.
`reasonType`	A representation of the type of error from which the notification recipient can decide how to handle the failure. Possible values include `RETRYABLE`, which indicates that the mutation should be able to be safely resubmitted, and `NON_RETRYABLE`, which indicates that the mutation should not be resubmitted and that an operator may want to review the state of their node(s).
`reasonText`	A human-readable message providing extra context for the failure.

An example of what the payload of a dead-letter notification could look like:

{
  "transactionId": "transaction_Id",
  "mutation": "updateSelf_Shipment(id:\"017d1206-7881-4279-995a-e4176d8f223a\",input: {delivered: true, lastUpdated: \"2020-12-02T14:10:02Z\", location: [47.3741, -122.031]}){error}",
  "owner": "shipper",
  "submissionTime": "2021-11-12T16:42:50.691102+00:00",
  "reasonType": "NON_RETRYABLE",
  "reasonText": "Verification failure during transaction processing."
}

Setting Up Notifications

Uni nodes can be configured to emit events for the following subscriber types:

HTTPS webhooks
Email addresses
AWS Lambda functions
Amazon SQS queues
Amazon Kinesis data firehoses
Azure Functions
Azure Queue Storage

For specifics on how to configure any of these subscribers for your node(s), see Getting Started with Notifications.

Limitations

Vendia’s Starter tier limits the number of real-time block notifications and dead-letter notifications received per Uni. See full details on the Pricing page.

Next Steps

Developing and Using Unis
Defining Your Data Model

Learning More

Application Performance Monitoring (APM) Integrations
Terms and Definitions