Technical deep dive #2: Getting Started with Geora’s GraphQL API

This blog is the second blog in our Technical Series, if you are new to Geora head here first for an introduction to our platform. Read the first blog in our technical series on our Event Sourcing Architecture.

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.

The Geora developer API

Registration

To set up a free developer’s account to experiment with the system, follow these steps.

1. Go to https://app.geora.io/developer and sign up with an email address.
2. Check your inbox for an email, follow the link and set your password.
3. Log in using your new password.
4. Save your API headers in a safe place, like a password manager, and note the API endpoint.

Sending a Request

GraphQL is a recent alternative to the REST method of designing HTTP APIs which allows the client to 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.

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 logged in user who can perform actions on the blockchain such as creating and transferring assets to other actors.

$ curl 'https://api.geora.io/v2'       \
 -H 'Content-Type: application/json' \
 -H 'x-api-key: <api-key>'           \
 -H 'x-api-user: <api-user>'         \
 -H 'x-geora-actor: <actor-id>'      \
 -d '{"query":"{actor(id: \"<actor-id>\") { id name email { email } } }"}'

We can use the actor ID from the x-geora-actor header in the query to get information about ourselves.

The response should look something like:

{
  "data": {
    "actor": {
      "id": <actor-id>,
      "name": "you@example.com",
      "email": { "email": "you@example.com" }
    }
  }
}

Inputs to the query that might vary frequently can be supplied separately to the query in a variables field as well. This query is equivalent to the previous one:

$ curl 'https://api.geora.io/v2'        \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api-key>'           \
  -H 'x-api-user: <api-user>'         \
  -H 'x-geora-actor: <actor-id>'      \
  -d @- <<EOF
{
  "query": "query Foo($id: ID!) {
    actor(id: $id) { id name email { email } }
  }",
  "variables": { "id": "<actor-id>" }
}
EOF

Mutations can also be invoked on the API to modify the state of the system; they take the role of POST, PUT and similar requests in REST. Here is how you might create a new asset in the system, which could represent having produced a harvest of 300 bushels of wheat:

$ curl 'https://api.geora.io/v2'        \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api-key>'           \
  -H 'x-api-user: <api-user>'         \
  -H 'x-geora-actor: <actor-id>'      \
  -d @- <<EOF
{ "query": "mutation {
  assetCreate(input: {
    class: \"WHEAT\",
    quantity:{ primaryValue: 300, primaryUnit: \"bu\" }
  }){ id }
}" }
EOF

Yielding a response such as:

{
  "data": {
    "assetCreate": {
      "id":"dXBkYXRlfGY4N2FmNWI4LTM4N[...]"
    }
  }
}

The Playground and Schema Explorer

Our backend server uses the Apollo Typescript library, which allows us to provide a handy playground for experimenting with the API.

1. Open the API endpoint https://api.geora.io/v2 in your browser.
2. Open the “HTTP HEADERS” tab at the bottom of the screen and paste in the API headers JSON object, from the developer portal.
3. Enter a query or mutation in the left pane, such as:

{
  actor(id: "<actor-id>") {
    id
    name
    email { email }
  }
}

4. Press the “Play” button in the centre of the screen to send the query, and see the response in the right pane.

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

Exploring the API with the schema view

Client Libraries

In our own client software we have been using the Elm language with a code generating client side tool, elm-graphql. This gives us a type-safe library for building GraphQL queries and mutations against our schema.

A simple example is fetching an actor as in the query above. We define a data type Actor to hold some actor information, its ID, name, and email address, and then the query definition (selActor) can declare that the query will construct an Actor value (SelectionSet Actor RootQuery).

type Msg = LoadedActor Actor
loadActor : Config -> Id -> Cmd Msg
loadActor cfg id = makeQuery cfg LoadedActor (selActor id)
type Actor = Actor Id String Email
selActor : Id -> SelectionSet Actor RootQuery
selActor id =
    Query.actor { id = id }
        (SelectionSet.succeed Actor
            |> with GeoraAPI.Object.Actor.id
            |> with (GeoraAPI.Object.Actor.name |> nonNullOrFail)
            |> with
                (GeoraAPI.Object.Actor.email
                    GeoraAPI.Object.EmailInfo.email
                    |> nonNullOrFail))
        |> nonNullOrFail

The fields we’re querying for, GeoraAPI.Object.Actor.id, GeoraAPI.Object.Actor.name, and GeoraAPI.Object.Actor.email, must be querying for fields of the correct types for the program to compile. Please see the elm-graphql documentation for more details.

More information

See the developer documentation at https://docs.geora.io/ for complete coverage of our GraphQL API. The documentation will walk you through simple examples and explain how the Geora API represents an entire supply chain, all the way from producer to consumer.

Want to keep up to date with everything happening at Geora? Sign up for our newsletter.

If you need development help, or support integrating your data with Geora, please contact us at hello@geora.io.