GraphQL

GraphQL is a query language for the BirdDog API. GraphQL provides a complete and understandable description of the data, and gives you the power to ask for exactly what you need and nothing more maing for an API that is easier to understand and performs better.

GraphQL versus REST

• REST has endpoints where you GET and POST while GraphQL has Query (read) and Mutation (insert/update/delete)
• REST typcally requires calls to multiple endpoint to get related data while GraphQL can traverse the object graph in a single request

GraphQL is most easily compared to REST. REST has the concept of "endpoints" which are created by the API developer. Those endpoints return a fixed amount of data. Because of this the endpoint developer has to decide what information to return. For example, imagine you have products (we'll call them items) that are stored at different warehouses (we'll call them locations). We could create a REST Item endpoint like this:

// GET /items/widgetxyz 
{
   "itemNo":"WIDGETXYZ",
   "description":"My amazing widget",
   "price":"10.98",
   "productCategory":"FG"
 // More fields here
   "locations":[
      {
         "code":"OK",
         "description":"Oklahoma",
         "quantityOnHand":99

         // More fields here
      },
      {
         "code":"TX",
         "description":"Texas",
         "quantityOnHand":23

         // More fields here
      }
   ]
}

 Notice that the endpoint developer has to decide what fields to return in the item enpoint. He also has to decide how to handle the sub-object warehouses. One option is to do it like we did above where the data is returned in the same call. Another option is to return a reference to another endpoint to get the warehouse information. This decreases the amount of data in this endpoints return but increases the number of calls to get all of the data you want.

GraphQL completely elimnates this problem by replacing all of the endpints with a single query endpoint and object types. Instead of the API developer deciding what informtion to return, the GraphQL consumer tells it what to return in the query. Imagine that the consumer only need the item's description, price, warehouse description, and quantity on hand. You can easily do that with the following query:

query {
  itemSearch(text: "widgetxyz") {
    description
    locations {
      location{
        description
        quantityOnHand
      }
    }
  }
}

This would return the following:

{
   "description":"My amazing widget",
   "locations":[
      {
         "description":"Oklahoma",
         "quantityOnHand":99
      },
      {
         "description":"Texas",
         "quantityOnHand":23
      }
   ]
}