DEV Community: Brian McNamara

Scale Your Partner Ecosystem with Vendia Share

Brian McNamara — Mon, 31 Jan 2022 16:39:56 +0000

Vendia Share simplifies the process of sharing data in real-time between organizations in a controlled, secure, and ledgered manner. Traditionally, sharing data in this manner is tough. There are several challenges that come to mind.

Challenges

Maintaining a single source of truth between organizations can be difficult. Databases are a popular information store, but securely sharing data from them with other organizations involves a number of compliance, security, and networking considerations that often mean slow action. Some organizations choose to share critical data with partners via spreadsheets. Using this method presents its own set of challenges. It's not apparent which spreadsheet is the latest and most complete source of truth.

Vendia Share helps you solve this problem by provisioning a node for each organization that you wish to share data with. Each node provides a consistent view of the data that is shared with other parties, and each node has its own API endpoint dedicated to the organization that needs to securely access the data.

Centralized approaches to data sharing often result in disjointed authentication (AuthN) and authorization (AuthZ). The central organization will likely have a preference for how partners will log in to access data. It will also likely have existing tooling and mechanisms in place to support users. However, partners in the data network may have different means of authenticating and managing users. Vendia Share is flexible enough to allow each participant in a Uni to configure their own authorization type.

Onboarding new participants to a partner data network historically has been difficult. Often technical teams need to update topologies and networks for each new addition. The steps involved to bring in a new partner can take days if not months. Vendia Share reduces the time to minutes and does without the support of highly valuable engineers, as you will see in this post.

Getting Started with Partner Onboarding

Creating Vendia Share Accounts

Vendia customers share data using a Vendia Share Universal Application (or "Uni" for short). Each participant in a Uni has a dedicated node for reading and writing data. We will simulate two companies sharing data by using two Vendia Share accounts. If you are not familiar with how to create a Vendia Share account, please consult our Getting Started documentation. We will refer to these accounts as Account 1 and Account 2. You will create your Uni using Account 1. Account 2 will be invited to join the Uni and create its own Vendia Share node.

NOTE: The example in the blog will use two separate Vendia Share accounts associated with the same email account. I've used the plus ("+") sign to associate two Vendia Share users with the same email account.

Creating a Uni

For the purposes of this walkthrough, we will use the Product Catalog from our Quick Starts. Once you've created a Uni using Account 1, feel free to proceed with the remainder of the steps in this blog.

NOTE: The commands below assume a Uni name of test-uni-management. Adjust commands below that use the Uni name to match the one you used.

Inviting Your Partner

Now that the Uni is up and running, you will invite Account 2 to the Uni. You can do this either with the Vendia Share web app or the Share CLI. For the purpose of this blog, you'll use the CLI syntax. My Account 1 e-mail address format is brian+account1@vendia.net and my Account 2 e-mail address is brian+account2@vendia.net.

Vendia Share features RBAC support for controlling who has access to your Uni - we will be posting a more detailed blog of how that capability works in a future blog post. One of the RBAC features is the ability to invite another Vendia user to create a node and join your Uni. We accomplish this task with the following command.

First, ensure you have authenticated to the Share CLI using the share login command. Be sure to use the Vendia account associated with Account 1.

% share login
> Enter your Vendia email address
Enter your email: brian+account1@vendia.net

> Enter your password for brian+account1@vendia.net
Password: *********

✔  Logged in as brian+account1@vendia.net

Once you have authenticated successfully, use the share uni invite command to begin the invitation process.

share uni invite --uni test-uni-management --user brian+account2@vendia.net

NOTE: The name of my Uni is test-uni-management. Be sure to adjust the command and use the name of the Uni you created.

You will see output that is similar to the following:

Invite Successful

User brian+account2@vendia.net successfully invited to Uni test-uni-management
brian+account2@vendia.net has been sent an email invite link.

For brian+account2@vendia.net to join, they must:
 - click email link
 - OR join by running the share uni join CLI command with the token below

Invite token:    12345678-abcd-1234-abcd-123456789012
Expires on:      2022-01-30T02:26:24.872624

We will export that invite token as an environment variable (be sure to substitute your invite token in the syntax that follows)

# This command will save the Invite token for later use by **Account 2**
export VENDIA_TOKEN=12345678-abcd-1234-abcd-123456789012

Your Account 2 email address should have a message from Vendia, inviting you to join the Uni created by Account 1.

Joining the Uni with Account 2

You can use the Vendia Share web app when logged in as Account 2 to complete the Uni join process. You can click on the link included in the invitation email. However, I will show you how to use the Share CLI to complete the same task.

NOTE: Make sure you've created the VENDIA_TOKEN variable from the share uni invite output.

You will need to log out using share logout and log back in with share login. Specify the email address and password associated with Account 2.

% share logout
You are now logged out of brian+account1@vendia.net

Run "share login" to log back in
% share login
> Enter your Vendia email address
Enter your email: brian+account2@vendia.net

> Enter your password for brian+account2@vendia.net
Password: *********

✔  Logged in as brian+account2@vendia.net

Once you're authenticated as Account 2 you can run share uni join to accept the invitation and specify your node's settings.

share uni join --uni test-uni-management \
--token $VENDIA_TOKEN \
--config '{"name":"account2-node","userId":"brian+account2@vendia.net", "region":"us-west-2", "settings": {"apiSettings": {"auth": {"authorizerType": "API_KEY"}}}}'

You will see output similar to the following:

addition of new node account2-node in uni addition of new node account2-node in uni test-uni-management.unis.vendia.net is now in progress

NOTE: The name of my Uni is test-uni-management. Be sure to adjust the command and use the name of the Uni you created.

You can observe the deployment process of the Node for Account 2 by running the share get command.

share get --uni test-uni-management

You will see output similar to the following

Getting test-uni-management info...
┌─────────────────────┐
│   Uni Information   │
└─────────────────────┘
Uni Name:    test-uni-management.unis.vendia.net
Uni Status:  ADDING
Node Count:  2
Nodes Info:
├─ ⬢ ProductCatalog
│  ├─ name: ProductCatalog
│  ├─ status: RUNNING
│  └─ resources:
└─ ⬢ account2-node
   ├─ name: account2-node
   ├─ status: DEPLOYING
   └─ resources:

To display schema & initial state, use the --json flag. Example: "share get test-uni-management.unis.vendia.net --json"

The node creation process will take a few minutes. When the node creation is complete, feel free to step through the Product Catalog Quick Start and observe how data updates can be viewed by both participants in the Uni.

Cleanup

Once you are finished running the example you can delete the Uni. You will run the share uni delete command as Account 1.

share uni delete --uni test-uni-management

WARNING: Deleting a Uni is destructive and will remove all of its underlying data.

NOTE: The name of my Uni is test-uni-management. Be sure to adjust the command and use the name of the Uni you created.

Summary

In this blog post, you created a Uni and added a second participant in minutes, allowing multiple partners to quickly and securely share data in real-time. Once you have completed the walkthrough, feel free to share your results on social media and tag Vendia (Twitter: @VendiaHQ, Linkedin: Vendia) so that we can see what you built!

Why We Combined GraphQL and a Serverless Distributed Ledger

Brian McNamara — Wed, 19 Jan 2022 22:30:00 +0000

Vendia Share is a SaaS offering that takes away the toil required to share data with partners in a controlled, secure, and ledgered manner. We do this by allowing customers to create Universal Applications (Unis) and inviting their partners to participate.

Each participant in a Uni has cloud resources created on their behalf. One of the resources is a managed, scalable, resilient, and secure GraphQL API that allows partners to create web, mobile, and backend applications to read data from and write data to a Uni.

While technical readers may be familiar with the concept of a REST API, there may be some among you who are not as familiar with GraphQL. For those of you with GraphQL experience, Vendia Share does take a non-traditional approach in some areas as well. In this post, we'll dive a bit deeper and explore GraphQL and look at why Vendia selected GraphQL as its primary interface. Through this post, you'll learn more about GraphQL and how it can improve your development experience with Vendia Share.

What is GraphQL?

GraphQL was created by Meta / Facebook in 2012 as a way to solve problems encountered when rebuilding their native mobile applications. The team was frustrated with the differences between the data they wanted to use in their applications and the server queries that were required and was challenged to pull in data from many disparate sources. They saw the importance of seeing data not just as a resource but as a graph.

GraphQL is a query language for APIs and a runtime for fulfilling those queries with existing data. GraphQL is a open specification; it is not controlled or managed by a single vendor. GraphQL clients and servers can be written in a number of programming languages. There is no requirement to use particular data stores to persist data.

What are Some Benefits of GraphQL?

There are several notable benefits of using GraphQL.

Data Precision

GraphQL allows clients to request exactly what they need and nothing more. This means that developers don't have to worry about over-fetching and under-fetching data. It's not uncommon to experience these issues when using other API strategies like REST. Eliminating these minimizes the number of network requests and client memory use required to satisfy an application's needs.

Many Resources in One Request

GraphQL allows applications to get all the data they need - even if they are different types - in a single request. This means fewer requests and, ultimately, more responsive applications for end users.

Strong Typing

GraphQL is strongly typed. This means that developers can know what is required by a GraphQL server to satisfy a request without having to be planning for type mismatches.

Subscriptions

Subscriptions provide a mechanism for fetching data from a GraphQL server over a long-lived connection (usually via WebSocket). They are a handy mechanism for providing updates to GraphQL clients when new objects are created or existing objects have updates made.

Vendia Share + GraphQL

Let's dive a bit deeper into Vendia Share's usage of GraphQL.

Vendia Share Foundations

Unis are created in part by a data model. This model is expressed through the JSON Schema Draft-07 standard and is used by the Vendia Share service to create GraphQL APIs for each participant. The API allows developers to run queries and mutations to interact with their data model. Because these capabilities are automatically created by Vendia Share, developers don't need to be concerned about developing and maintaining them.

Why Did Vendia Pick GraphQL?

We had to make a choice regarding API standards in our very early days. It came down to selecting either REST or GraphQL. Spoiler alert - we chose GraphQL. Here are a few specific dimensions we considered.

Performance

It's not easy to build out functionality to allow developers to selectively choose data to return just the data they want via REST. Yes, it can be done. However, the problems of over-fetching and under-fetching remain - they just shift to the API provider. We made a conscious decision early to use GraphQL so that we would not be incurring additional compute or data transfer hits resulting from over- and under-fetching.

Subscriptions are Easier

REST does not have a great pattern for asynchronous, server-side updates to clients other than polling, rolling-your-own, or using HTTP/2 throughout. We see GraphQL subscription operations as a better method to receive these updates. Applications can use WebSockets to detect when changes have been made.

Developer Friendly

There are a number of programming language clients and frameworks that support GraphQL. We would not be introducing additional burden on developers of our platform. In addition, developers have the built-in ability to introspect to learn how to read from and write data to their Uni.

Accommodating Changes to the Uni Data Model

We recognized the shape of data stored in a Uni would likely evolve over time as business needs changed. We felt it would be easier to accommodate these changes using GraphQL in an automated manner that simply worked.

Summary

In my experience, having context affords better understanding. We felt it important to understand not just what GraphQL is - although it is super important when working with Vendia Share - but why we've made the decision to choose GraphQL for our API strategy in the first place. We've created some code examples that demonstrate how to interact with Vendia-generated GraphQL APIs using several programming languages. Stay tuned for an upcoming post where we'll dive a bit deeper into how you can take advantage of some Vendia-specific GraphQL goodies like transactions, conditional operations, and examining GraphQL operations that have been committed to your Uni.