Playing with Facebook's GraphQL (applied to AWS products and offers management)
About GraphQL
GraphQL has been invented by Facebook for the purpose of refactoring their mobile application. Facebook had reached the limits of the standard REST API mainly because:
- Getting that much information was requiring a huge amount of API endpoints
- The versioning of the API was counter-productive regarding Facebook’s frequents deployements.
But graphql is not only a query language related to Facebook. GraphQL is not only applicable to social data.
Of course it is about graphs and graphs represents relationships. But you can represent relationships in all of your business objects.
Actually, GraphQL is all about your application data.
In this post I will try to take a concrete use case. I will first describe the business objects as a graph, then I will try to implement a schema with GraphQL. At the very end I will develop a small GraphQL endpoint to test the use case.
Caution I am discovering GraphQL on my own. This post reflects my own work and some stuff may be inaccurate or not idiomatic.
The use case: AWS billing
Let’s take a concrete example of a graph representation. Let’s imagine that we are selling products related to Infrastructre as a Service (IaaS).
For the purpose of this post, I will use the AWS data model because it is publicly available and I have already blogged about it. We are dealing with products families, products, offers and prices.
In (a relative) proper english, let’s write down a description of the relationships:
- Products
- A product family is composed of several products
- A product belongs to a product family
- A product owns a set of attributes (for example its location, its operating system type, its type…)
- A product and all its attributes are identified by a stock keeping unit (SKU)
- A SKU has a set of offers
- Offers
- An offer represents a selling contract
- An offer is specific to a SKU
- An offer is characterized by the term of the offer
- A term is typed as either “Reserved” or “OnDemand”
- A term has attributes
- Prices
- An offer has at least one price dimension
- A price dimension is characterized by its currency, its unit of measure, its price per unit, its description and eventually per a range of application (start and end)
Regarding those elements, I have extracted and represented a “t2.micro/linux in virginia” with 3 of its offers and all the prices associated.
Here is the graphical representation generated thanks to graphviz’ fdp
The goal of GraphQL is to extract a subtree of this graph to get part or all information. As an example, here is a tree representation of the same graph:
Note: I wrote a very quick’n’dirty parser to get the information which can be found here. I wrote an idiomatic one but it is the property of the company I made it for.
Defining the GraphQL schema
The first thing that needs to be done is to write the schema that will define the query type.
I will not go into deep details in here. I will simple refer to this excellent document which is a résumé of the language: Graphql shorthand notation cheat sheet
We can define a product that must contains a list of offers this way and a product family like this:
1# Product definition
2type Product {
3 offers: [Offer]!
4 location: String
5 instanceType: String
6 sku: String!
7 operatingSystem: String
8}
9
10# Definition of the product family
11type ProductFamily {
12 products: [Product]!
13}One offer is composed of a mandatory price list. An offer must be of a pre-defined type: OnDemand or Reserved. Let’s define this:
1# Definition of an offer
2type Offer {
3 type: OFFER_TYPE!
4 code: String!
5 LeaseContractLength: String
6 PurchaseOption: String
7 OfferingClass: String
8 prices: [Price]!
9}
10
11# All possible offer types
12enum OFFER_TYPE {
13 OnDemand
14 Reserved
15}
16
17# Definition of a price
18type Price {
19 description: String
20 unit: String
21 currency: String
22 price: Float
23}At the very end we define the queries Let’s start by defining a single query. To make it simple for the purpose of the post, Let’s assume that we will try to get a whole product family. If we query the entire product family, we will be able to display all informations of all product in the family. But let’s also consider that we want to limit the family and extract only a certain product identified by its SKU.
The Query definition is therefore:
1# root Query type
2type Query {
3 products(sku: String): [Product]
4}We will query products ({products}) and it will return a ProductFamily.
Query
Let’s see now how a typical query would look like. To understand the structure of a query, I advise you to read this excellent blog post: The Anatomy of a GraphQL Query.
1{
2 ProductFamily {
3 products {
4 location
5 type
6 }
7 }
8}This query should normally return all the products of the family and display their location and their type. Let’s try to implement this
Geek time: let’s go!
I will use the go implementation of GraphQL which is a “simple” translation in go of the javascript’s reference implementation.
To use it:
1import "github.com/graphql-go/graphql"To keep it simple, I will load all the products and offers in memory. In the real life, we should implement an access to whatever database. But that is a strength of the GraphQL model: The flexibility. The backend can be changed later without breaking the model or the API.
First pass: Only the products
Defining the schema and the query in go
Most of the work has already been done and documented in a series of blog posts here
First we must define a couple of things:
- A Schema as returned by the function
graphql.NewSchemathat takes as argument agraphql.SchemaConfig - The
graphql.SchemaConfigis a structure composed of aQuery, aMutationand other alike fields which are pointers tographql.Object - The rootQuery is created by the structure
graphql.ObjectConfigin which we pass an object of typegraphql.Fields(which is amap[string]*Field)
The code to create the schema is the following:
1fields := graphql.Fields{}
2rootQuery := graphql.ObjectConfig{Name: "RootQuery", Fields: fields}
3schemaConfig := graphql.SchemaConfig{
4 Query: graphql.NewObject(rootQuery),
5}
6schema, err := graphql.NewSchema(schemaConfig)Defining the fields
Our shema is created but nearly empty because we did not filled the “fields” variable. the fields variable will contain what the user can request.
As seen before, fields is a map of *Field. The key of the map is the root query. In our definition of the Query, we declared that the query would be “products”. So “products” is the key of the map.
The graphql.Field that is returned is a list type composed of productTypes.
1fields := graphql.Fields{
2 "products": &graphql.Field{
3 Type: graphql.NewList(productType),
4 ...We will see in a minute how to define the productType. Before, we must provide a way to seek for the product in the database.
This is done by implementing the Resolve function:
1fields := graphql.Fields{
2 "products": &graphql.Field{
3 Type: graphql.NewList(productType),
4 Resolve: func(p graphql.ResolveParams) (interface{}, error) {
5 ...The resolv function will return all the products in our database.
But wait… In the Query definition, we said that we wanted to be able to limit the product by setting a sku in the query.
To inform our schema that it can handle a we add the Args field to the graphql.Field structure:
1fields := graphql.Fields{
2 "products": &graphql.Field{
3 Type: graphql.NewList(productType),
4 Args: graphql.FieldConfigArgument{
5 "sku": &graphql.ArgumentConfig{
6 Type: graphql.String,
7 },
8 },
9 Resolve: func(p graphql.ResolveParams) (interface{}, error) {
10 ...as the argument is not mandatory, we will use an if statement in the Resolve function to check whether we have a sku or not:
1if sku, skuok := p.Args["sku"].(string); skuok {Defining the productType
To be able to query display the information of the product (and query the fields), we must define the productType as a graphql object. This is done like this:
1var productType = graphql.NewObject(graphql.ObjectConfig{
2 Name: "Product",
3 Fields: graphql.Fields{
4 "location": &graphql.Field{
5 Type: graphql.String,
6 },
7 "sku": &graphql.Field{
8 Type: graphql.String,
9 },
10 "operatingSystem": &graphql.Field{
11 Type: graphql.String,
12 },
13 "instanceType": &graphql.Field{
14 Type: graphql.String,
15 },
16 },
17})A productType is a graphql object composed of the 4 fields. Those fields will be returned as string in the graphql.
Querying
I will not implement a webservice to query my schema by now. This can easily be done with some handlers that are part of the project. I will use the same technique as found on internet: I will put the query as argument to my cli.
Assuming that query actually holds my my graphql request, I can query my schema by doing:
1params := graphql.Params{Schema: schema, RequestString: query}
2r := graphql.Do(params)
3if r.HasErrors() {
4 log.Fatalf("Failed due to errors: %v\n", r.Errors)
5}A couple of tests…
./pricing -db bla -query "{products(sku:\"HZC9FAP4F9Y8JW67\"){location}}" | jq "."
1{
2 "data": {
3 "products": [
4 {
5 "location": "US East (N. Virginia)"
6 }
7 ]
8 }
9}./pricing -db bla -query "{products(sku:\"HZC9FAP4F9Y8JW67\"){location,instanceType}}" | jq "."
1{
2 "data": {
3 "products": [
4 {
5 "location": "US East (N. Virginia)",
6 "instanceType": "t2.micro"
7 }
8 ]
9 }
10}./pricing -db bla -query "{products{location}}" | jq "." | head -15
1{
2 "data": {
3 "products": [
4 {
5 "location": "US East (Ohio)"
6 },
7 {
8 "location": "EU (Frankfurt)"
9 },
10 {
11 "location": "EU (Frankfurt)"
12 },
13 {
14 "location": "Asia Pacific (Sydney)"
15 },./pricing -db bla -query "{products{location,operatingSystem}}" | jq "." | head -20
1{
2 "data": {
3 "products": [
4 {
5 "operatingSystem": "Windows",
6 "location": "Asia Pacific (Sydney)"
7 },
8 {
9 "operatingSystem": "Windows",
10 "location": "AWS GovCloud (US)"
11 },
12 {
13 "operatingSystem": "Windows",
14 "location": "Asia Pacific (Mumbai)"
15 },
16 {
17 "operatingSystem": "SUSE",
18 "location": "US East (N. Virginia)"
19 },Adding the Offers
To add the offer, we should first define a new offerType
1var offerType = graphql.NewObject(graphql.ObjectConfig{
2 Name: "Offer",
3 Fields: graphql.Fields{
4 "type": &graphql.Field{
5 Type: graphql.String,
6 },
7 "code": &graphql.Field{
8 Type: graphql.String,
9 },
10 "LeaseContractLenght": &graphql.Field{
11 Type: graphql.String,
12 },
13 "PurchaseOption": &graphql.Field{
14 Type: graphql.String,
15 },
16 "OfferingClass": &graphql.Field{
17 Type: graphql.String,
18 },
19 },
20})And then make the productType aware of this new type:
1var productType = graphql.NewObject(graphql.ObjectConfig{
2 Name: "Product",
3 Fields: graphql.Fields{
4 "location": &graphql.Field{
5 Type: graphql.String,
6 },
7 "sku": &graphql.Field{
8 Type: graphql.String,
9 },
10 "operatingSystem": &graphql.Field{
11 Type: graphql.String,
12 },
13 "instanceType": &graphql.Field{
14 Type: graphql.String,
15 },
16 "offers": &graphql.Field{
17 Type: graphql.NewList(offerType),
18 },
19 },
20})Then, make sure that the resolv function is able to fill the structure of the product with the correct offer.
Testing:
./pricing -db bla -query "{products(sku:\"HZC9FAP4F9Y8JW67\"){location,instanceType,offers{type,code}}}" | jq "."
1{
2 "data": {
3 "products": [
4 {
5 "offers": [
6 {
7 "type": "OnDemand",
8 "code": "JRTCKXETXF"
9 }
10 ],
11 "location": "US East (N. Virginia)",
12 "instanceType": "t2.micro"
13 }
14 ]
15 }
16}This is it!
Conclusion
I didn’t document the prices, but it can be done following the same principles.
Graphql seems really powerful. Now that I have this little utility, I may try (once more) to develop a little react frontend or a GraphiQL UI. What I like most is that it has forced me to think in graph instead of the traditional relational model.
The piece of code is on github
edit: I have included a graphiql interpreter for testing. It works great. Everything is on github:
