ResilientDB GraphQL

ResilientDB GraphQL is a proxy or gateway that provides multiple ways to interact with ResilientDB. This gateway offers both REST API and GraphQL interfaces, allowing developers to choose their preferred method of interaction.

Overview

ResilientDB GraphQL serves as a bridge between your applications and the ResilientDB blockchain network. It provides:

REST API endpoints for traditional HTTP-based interactions
GraphQL interface for flexible, query-based data access

REST API Usage

The REST API provides a straightforward way to interact with ResilientDB using standard HTTP methods.

Create Transaction

Set Transaction by Key-Value Pair


# Set a transaction by a id (key) and its value
curl --location 'https://crow.resilientdb.com/v1/transactions/commit' \
--header 'Content-Type: application/json' \
--data '{
    "id": "key_test",
    "value": "value_test"
}'

This curl command can be directly imported into Postman. In Postman, you can:

Click “Import” and paste the curl command
Use the “Code” button to generate equivalent code in TypeScript, Python, or other languages
Save the request to a collection for future use

Response Examples

Success Response (201 Created):


  id: key_test

Error Response (400 Bad Request):


  Invalid transaction format

Unavailable Service (503 Service Unavailable):


  Service Unavailable

GET Transaction

Get Transaction by Key


# Get a transaction by key
curl --location 'https://crow.resilientdb.com/v1/transactions/key_test'

Response Examples

Success Response (200 OK):


{
  "id": "key",
  "value": "value"
}

If key is not found, it will return an empty object.

{}

Unavailable Service (503 Service Unavailable):


  Service Unavailable

GraphQL Usage

The GraphQL interface provides a more flexible way to query and mutate data in ResilientDB.Access the GraphQL Playground at GraphQL Playground to interactively explore and test queries.

The GraphQL Playground is a great tool for testing queries and mutations before implementing them in your code.

Create Transaction


mutation Test($data: PrepareAsset!) {
  postTransaction(data: $data) {
    id
  }
}

Variables


{
  "data": {
    "operation": "CREATE",
    "amount": 1,
    "signerPublicKey": "YOUR_SIGNER_PUBLIC_KEY",
    "signerPrivateKey": "YOUR_SIGNER_PRIVATE_KEY",
    "recipientPublicKey": "YOUR_RECIPIENT_PUBLIC_KEY",
    "asset": {
      "data": {
        "drawingId": "drawing_testing_random_seed",
        "color": "#000000",
        "lineWidth": 5,
        "pathData": [{"x": 292, "y": 126}],
        "timestamp": 1746736411543,
        "user": "appleseed|1746736304144",
        "brushStyle": "round",
        "order": 1746736411543
      }
    }
  }
}

GET Transaction by ID


query GetTx($id: ID!) {
  getTransaction(id: $id) {
    id
    version
    amount
    uri
    type
    publicKey
    operation
    metadata
    asset
    signerPublicKey
  }
}

Variables


{
  "id": "transaction_id"
}

Python Example


from pyodide.http import pyfetch
import json
 
# GraphQL endpoint
url = "https://cloud.resilientdb.com/graphql"
 
# Query and variables
query = """
query GetTx($id: ID!) {
    getTransaction(id: $id) {
        id
        version
        amount
        uri
        type
        publicKey
        operation
        metadata
        asset
        signerPublicKey
    }
}
"""
 
variables = {
    "id": "6358ee73fb6bf5c659676ccc8476ebb6ea738b47a101661697ef379e5ea0212b"
}
 
# Prepare the payload
payload = {
    "query": query,
    "variables": variables
}
 
# Make the request
response = pyfetch(
    url,
    method="POST",
    headers={"Content-Type": "application/json"},
    body=json.dumps(payload)
)
 
# Print the response
print(response.json())

Response Examples

Success Response (200 OK):


{
  "data": {
    "getTransaction": {
      "id": "6358ee73fb6bf5c659676ccc8476ebb6ea738b47a101661697ef379e5ea0212b",
      "version": "2.0",
      "amount": "1",
      "uri": "",
      "type": "CREATE",
      "publicKey": "YOUR_PUBLIC_KEY",
      "operation": "CREATE",
      "metadata": null,
      "asset": {
        "data": {
          "drawingId": "drawing_testing_random_seed",
          "color": "#000000",
          "lineWidth": 5,
          "pathData": [{"x": 292, "y": 126}],
          "timestamp": 1746736411543,
          "user": "appleseed|1746736304144",
          "brushStyle": "round",
          "order": 1746736411543
        }
      },
      "signerPublicKey": "YOUR_SIGNER_PUBLIC_KEY"
    }
  }
}

Error Response (404 Not Found):


{
  "errors": [
    {
      "message": "Transaction not found",
      "path": ["getTransaction"]
    }
  ]
}

Never share your private keys. Always use environment variables or secure key management systems to store sensitive credentials.

Response Examples

Success Response (200 OK):


{
  "data": {
    "postTransaction": {
      "id": "transaction_id"
    }
  }
}

Error Response (400 Bad Request):


{
  "errors": [
    {
      "message": "Invalid input",
      "path": ["postTransaction"]
    }
  ]
}

API Reference Summary

REST Endpoints

GET /v1/transactions/{id}: Get a single transaction
POST /v1/transactions/commit: Create a new transaction

GraphQL Operations

Queries

getTransaction(id: ID!): Get a single transaction

Mutations

postTransaction(data: PrepareAsset!): Create a transaction

Playground

Try out the examples in our interactive playground. You can experiment with both REST API and GraphQL operations.

Initializing Python environment...

The playground provides a safe environment to test your code. All examples are pre-configured with the correct endpoints and authentication.

Best Practices

Error Handling
- Always implement proper error handling
- Check response status codes
- Handle network errors gracefully
Transaction Management
- Use appropriate transaction types
- Validate data before sending
- Keep track of transaction IDs
Security
- Never expose private keys
- Use environment variables for sensitive data
- Implement proper authentication

Next Steps

Ready to set up ResilientDB GraphQL on your system? Check out the Setup Guide for detailed installation instructions.

Contributing

We welcome contributions! Please see our README for more details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.