Using the GraphQL API

Each node in a Uni hosts a GraphQL API that provides full CRUD support for your data model in addition to extended functionality such as working with Files.

Queries

Vendia generates the following GraphQL queries for the top-level entities in your data model.

get_X

Supports retrieving an item by id. An optional version number parameter can be provided to query for the state of the item at a particular version.

list_XItems

Supports listing items. List results can be filtered using the filter parameter. For data models with indexes defined, list filters will automatically use the first matching index found. Returns a nextToken that can be used for pagination.

list_XVersions

List the versions of a particular object. The returned result contains the ordinal version numbers as well as block and transaction metadata. The version number can be used in a get query to retrieve the object at a particular version. Returns a nextToken that can be used for pagination.

type Vendia_Version {
    ordinal: Int!
    block: String!
    transactions: [Vendia_Version_Transaction]
}

Mutations

GraphQL mutations allow clients to modify objects defined in the data model. All mutations modify the state of an object, store the change in the global ledger, and store a new version record for the object.

Mutations return a transaction result object that contains both transaction metadata and the contents of the updated object:

type Self_MyObject_Transaction_Result_ {
    transaction: Vendia_Transaction!
    result: Self_MyObject
}
type Vendia_Transaction {
    _id: String!  # id of the modified object
    _owner: String!
    transactionId: String!
    version: String!
    submissionTime: String!
}

For example, the following mutation:

add_Shape(
   syncMode: NODE_LEDGERED, 
   input: { 
       name: "square", 
       numSides: 4
   }
) { 
   transaction { 
       transactionId 
   }
   result {
       _id 
       name 
       numSides 
   } 
 }

returns the result:

{
    "transaction": {
        "transactionId": "f54160b5-58f1-485c-9745-737e539eb262"
    },
    "result": {
        "_id": "234160b5-58f1-485c-9745-737e539eb20f"
        "transactionId": "",
        "name": "square",
        "numSides": 4
    }
}

Vendia supports multiple synchronization modes for mutation operations, specified by the syncMode parameter. This determines when the operation returns the result to the client.

• ASYNC: Queues the transaction for consensus and returns immediately. With ASYNC, the result property in the response will always be empty. Clients can configure GraphQL subscriptions to receive notifications when transactions are committed.
• NODE_LEDGERED: This synchronous mode returns the result once the transaction has been committed and ledgered on the local node. The transaction is guaranteed to be eventually replicated to all the nodes in the Uni.

Synchronous mutation responses include a result property that contains the version of the object following the submitted transaction. The returned result is read-isolated against other concurrent writes to the object. To retrieve the latest version of the object, you can use a get query without the version number specified.

Note: Mutations return a transactionId that can be used for status polling and correlation purposes. To configure failure notifications for mutations, see Dead-letter notifications.

Vendia generates the following GraphQL mutations for the top-level entities in your data model.

add_X / remove_X

Supports adding and removing items for array types.

create_X / delete

Supports creating and deleting items for object types.

put_X

Put mutations update an item by replacing the entire item with the input specified in the mutation. All required fields must be specified in the input, and any absent fields will be removed in the datastore.

i.e.

put_Shape(
   id: "234160b5-58f1-485c-9745-737e539eb20f",
   syncMode: ASYNC,
   input: { 
       name: "square", 
       color: "red", 
       numSides: 4 
   }
) { transaction { transactionId } }

update_X

Supports partial update of an item. Only the fields specified in the input will be updated. Fields absent in the input are preserved in the datastore. Fields can be explicitly removed by specifying a null value.

i.e.

update_Shape(
   id: "234160b5-58f1-485c-9745-737e539eb20f",
   syncMode: NODE_LEDGERED, 
   input: { 
       name: null, 
       numSides: 5
   }
) { 
   transaction { _id transactionId }
   result { name numSides } 
 }

This mutation removes the name field, preserves the existing value of the color field, and updates the numSides field.

Note: Nested objects can be explicitly removed if they do not contain required fields. i.e.

update_MyObject(
   id: "234160b5-58f1-485c-9745-737e539eb20f",
   syncMode: NODE_LEDGERED, 
   input: { 
       nestedObject: null
   }
) {
   transaction { _id transactionId }
   result { name numSides } 
}

Next Steps

Using File Storage

Integrating a Vendia chain with other Cloud, Web, and Mobile Services

Learning More

Terms and Definitions