Creating the Agriculture Industries first GraphQL API

Farming…a centuries-old practice that Australia is famous for. Despite still being considered a fairly traditional industry, the members of its supply chain are always looking for better ways to improve how they work, how they improve traceability, reduce the mandatory governance overhead and get more time time to get back to doing their day-to-day job.

From 2018-2021 we had the pleasure of working with Australia's red meat governing body to case studyCreating tomorrow’s livestock provenance / supply chainresearch, design and develop their integral platform for handling livestock consignments and movements.

The problem

If you’ve worked in large organisations, government agencies or even well-established startups, you’d probably be familiar with monolithic architectures. These are platforms that most likely started small and grew into the behemoth they are today, to meet the ongoing changes in the systems around them.

The Agricultural industry is no different, many of their current platforms rely on traditional REST APIs to transfer information between platforms and gateways. However, this practice is not without its problems:

Duplicate calls and data

As each REST API endpoint is configured to provide a set “piece” of data you often find yourself having to call multiple REST API endpoints just to get the bit you actually need. This chaining of requests can lead to issues where one of the requests does not complete causing the whole transfer to fail.

Poor performance for low-bandwidth users

Due to the nature of where these systems/platforms may be in use, the user could have a low-speed connection where every Kilobyte of bandwidth saved could be the difference between a successful journey or a failed one.

Not fun for developers

Developing traditional Rest APIs internally had its own challenges -keeping separate documentation up-to-date, testing requirements, and the extensive onboarding required to understand the flow of data throughout the different endpoints.

This left us pondering...

‘What would the Agricultural Industry’s first GraphQL API look like?’

The solution

The team decided to implement a new, platform-agnostic, federated GraphQL API. Put simply, we wanted to build an API that could be used for any number of different device types (Mobile/Web/Native etc) but also wrap other platforms that are currently in use so the end user only has to use one location to get what they need.

We decided to utilise GraphQL to solve some of the key problems. Our main areas of focus were:

• Providing a better experience for our end users

• Improved efficiencies for your development teams

• Enhanced development capability for third-party integrators/vendors

Providing a better experience for our end users

Real-world scenario: Imagine you are a Farmer, out in the field and you only have access to a slow 2G mobile connection.

This is fine for making phone calls, sending SMS or even handling basic tasks. But when you have to access a system in order to get your job done this can be infuriating.

Traditional systems, using REST APIs, put the burden of making multiple requests and downloading all that unnecessary data onto the user, whether they need it or not.

In a practical sense, it looks something like this. The farmer logs in to the website and is presented with their last 10 consignments (a consignment is basically a recorded movement of cattle).

Using traditional REST APIs would result in a number of different calls:

• Transaction: Get a list of transactions that have occurred recently

• Transaction Detail: Loop through the above list and get all the details of each transaction, this contains tons of data you don’t need

Instead with GraphQL, the frontend can control what data it needs to display, so in this case it would just say it needs:

• Movement ID

• Movement Date

• From Address

• To Address

Then, the response would only contain that data without all the extra fluff or things the user doesn’t need to see right now.

Long story short, by switching to GraphQL your frontend can request the data it needs at the time it needs it, helping reduce overhead for people with low bandwidth or poor connection speeds and enabling your development teams to build more performant, smarter, interfaces.

This switch can mean data savings of up to 80% compared to traditional REST APIs, which also means you can make massive savings for your hosting too.

Enhanced offerings for third-party integrators

We mentioned having to “chain” multiple REST API calls just to get to the data you need, well with GraphQL you only need to make one request to one endpoint.

This benefits the farmers and helps scale your platform to third-party integrators, vendors, and marketplaces and helps drastically reduce the need for additional documentation or training.

Improved efficiencies for your development teams

GraphQL comes with documentation “baked in” by default, this means anyone accessing or developing with your API can see a live representation of the overall schema, the queries they can make and the types of data it expects and returns (yay Typescript).

This drastically reduces your in-house onboarding time as well as the need to manually document the API in other systems, Swagger, or other places, like Contentful.

Another benefit is the strongly typed schema definitions help your QA teams to create resilient, automated tests that can alert you if your system is not doing what it's expected to do…which as we all know is much better than your users finding out and telling you.

Did I also mention that you can evolve and update your API with new fields and types without impacting your existing queries? Well with GraphQL you can continuously add features to your platform without impacting your current users or integrators.

Essentially, if you are releasing an MVP to market and are not using GraphQL…you could be in for a world of pain 💣

The outcome

Once the platform was released into the wild we noticed dramatically improved experiences for our end users, not only was this evident through an analytics deep-dive:

• Time to completion: How long it took someone to create and submit an animal movement

• Number of completions: How many animal movements were created

• Reduced number of support requests: Calls/Emails to the call centre

• Rage Clicks: How often people rage clicked or gave up a journey (HotJar)

But it was clear in the direct feedback, through HotJar NPS surveys, that people were finally able to complete new movements in minutes rather than hours.

This new approach also enabled the product team to rapidly develop new features, and functionality and improve on existing ones without worrying about how this may impact already existing integrations or platforms. This meant we had a far more positive impact with the integrators who were utilising these APIs in their own systems as they didn’t have to worry about it breaking all the time.