Geora is a blockchain-based system for managing and securing agricultural supply chains. For developers seeking to build supply chain applications, or custom integrations with the protocol, Geora provides a full-featured GraphQL API. In this post, you will learn how to start developing on Geora by connecting to and using the API.

Accessing the developer playground

To set up a free developer account to experiment with Geora, follow these steps:

Go to https://app.geora.io and sign up with an email address
Check your inbox for an email, follow the link and set your password
Log in using your new password
Follow the Build link in the sidebar

In the Build module, will find a link to the API playground and temporary authentication headers. You can use these credentials in the Headers tab of the playground to get started right away. These headers will expire and should not be used in production; see our guide to authentication.

Using the API

Geora offers a GraphQL API which allows developers to build full applications on the protocol. GraphQL is a query language that is well suited to Geora’s graph-like domain model. A user can choose, for each query, what data needs to be returned; and can combine results from many related objects in the API in the one query. This structured method of querying can reduce round trips and avoid transferring unnecessary data.

The API provides features like:

Creating and updating assets
Managing asset data and permissions
Uploading certificates and verifying claims

It also provides a query interface to create rich queries on objects like assets, asset versions, actors, and files.

Your first query

A basic query to begin with is to fetch some information about your own actor in the system. An actor in the Geora system represents a person or organisation who can perform actions such as creating and transferring assets to other actors. Here, we ask for all actors which we are authorised to view, and request their ID, name, email address, and any claims or metadata on the actors.

{
  actors {
    edges {
      node {
        id
        name
        email {
          email
          isVerified
        }
        
        claims {
          edges {
            node {
              label
              value
            }
          }
        }
      }
    }
  }
}

The response should look something like:

{
  "data": {
    "actors": {
      "edges": [
        {
          "node": {
            "id": "YWN0b3J8NzRjZDRiYjQtMjUxOC00OGZkLTgxOGEtYmNlMWRlYjU2MzA0",
            "name": "Geora Organics",
            "email": {
              "email": "[email protected]",
              "isVerified": false
            },
            "claims": {
              "edges": []
            }
          }
        }
      ]
    }
  }
}

In the API playground, the query is in the left panel, and the response is on the right. Make sure you copy your temporary authentication header into the HTTP Headers section down the bottom!

Exploring the API

The DOCS and SCHEMA buttons down the right hand side of the playground open helpful views for exploring the GraphQL schema. We can see the possible queries (actor(...), asset(..), etc.) and the mutations/write operations (assetCreate(...), etc.), and by clicking them can seek down through the tree of types used in the query or mutation to see what values can be requested.

Full documentation for all API endpoints is available at docs.geora.io.

Need some help? 🤔

Get in touch using the live chat button to the bottom right of any Geora page and you'll be connected to us in real time! 👉