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

Ben Sinclair
Oct 27, 2020 · 5 min read

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.

Image for post
Image for post
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.

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.
{
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.

Image for post
Image for post
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 ActorloadActor : Config -> Id -> Cmd Msg
loadActor cfg id = makeQuery cfg LoadedActor (selActor id)
type Actor = Actor Id String EmailselActor : 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.

Geora

A commercial blockchain protocol to trace, trade and…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store