An Introduction to GraphQL

The Red Flag Alert (RFA) API is based on GraphQL.

This technology allows relationships between business entities to be quickly retrieved in a single call. As such it has several advantages over the more traditional REST (Representational State Transfer) APIs.

Advantages over RESTful APIs:

No more over-fetching

RESTful API endpoints return everything they have been programmed to return.

For example, let’s say you’re interested in a company’s net worth over time. With the traditional Red Flag RESTful API you would have to query the balance-sheet endpoint:

curl -u "KEY:SECRET" "https://api2.redflagalert.net/v4/companies/01777777/balance-sheet/"

What gets returned is an array of JSON objects containing all the balance sheet information for each year on record.

Each record will look something like this:

{
           "attributes": {
               "account_date": "2021-12-31",
               "audit_qual": "FULLY AUDITED",
              "no_weeks": 52,
               "currency": "GBP",
               "tangible_fixed_assets": 9861000000,
               "intangible_assets": 1032000000,
               "total_fixed_assets": 14917000000,
               …
               "share_capital_reserve": 1660000000,
               "pl_account_reserve": 132000000,
               "revaluation_reserve": 0,
               "shareholders_funds": 1792000000,
               "working_capital": -3495000000,
               "net_worth": 760000000,
               "total_assets": 17764000000,
               "contingent_liabilities": 19000000
           },
           "type": "balance_sheet",
           "id": "645323-64532320211231"
       },

You get every attribute associated with that year’s profit and loss data (working capital, total assets etc.) even though you’re only interested in the net worth.

Conversely, using GraphQL you can specify that you only want the net worth value and that’s all that gets returned.

So, in this case the query would look like this:

query example1 {
companies(where: {company_number: {eq: "01777777"}}) {
   items {
     balance_sheet{
         net_worth
     }
   }
}
}

…and the results would look like this:

"data": {
   "companies": {
     "items": [
       {
         "balance_sheet": [
           {
             "net_worth": 760000000
           },
           {
             "net_worth": 505000000
           },
           {
             "net_worth": 4713000000
           },

Note that the results are presented in JSON format so they are easily parseable by the same code and libraries that you would use to parse the results of a traditional RESTful API call.

Single End Point

Let’s suppose you want to combine the net worth figure with the retained profit figure from the profit and loss endpoint. With the traditional RESTful API, you would have to call two endpoints:

"https://api2.redflagalert.net/v4/companies/01777777/balance-sheet/"
and
"https://api2.redflagalert.net/v4/companies/01777777/profit-loss/"

Again, the profit-loss endpoint would return all the data associated with the profit and loss for each year. So, you would then have to pull out just the net worth figure from the balance sheet and the retained profit figure from the profit and loss – having had to call two different API end points.

Contrast this with the same query in GraphQL:

query example2 {
companies(where: {company_number: {eq: "01777777"}}) {
   items {
     balance_sheet{
         net_worth
     }
     profit_loss {
       retained_profit
     }
   }
}
}

One call – and one set of results containing just the fields in which you’re interested.

Get Multiple Results

A RESTful endpoint typically only allows you to retrieve data for a single company at a time since the unique company identifier (typically the 8 character Company Number for UK businesses) is part of the URL.

GraphQL allows you to specify multiple company identifiers and for you to pull the requested data back for all those companies in a single call. This can be very useful if you're trying to enhance the data for - say - 1,000 companies. Instead of making 1,000 separate calls (even more if the data is spread across different RESTful API endpoints) you can make a single call.

For example:

query example2 {
companies(where: {company_number: {in: ["11266456","01777777" ... ]}}) {
  items {
    balance_sheet{
        net_worth
    }
    profit_loss {
      retained_profit
    }
  }
}
}

This technique can substantially reduce the time taken to enhance data.

Summary of Advantages

To summarise the advantages of GraphQL are:

• GraphQL is faster since there is usually only one call to retrieve multiple data points.
• You only return the data you require and no more.
• You can fetch data for multiple records with a single call.

If you have any further questions, please reach out to our Support Team via Contact Us.