Building Better Django WEB APIs with GraphQL Tutorial -- Words (960)

Django and GraphQL

GraphQL is a new technology of building APIs created and open sourced ,in February 2015 ,by Facebook so how does it differ from the old way of building HTTP Rest APIs ?

Tutorial Parts :

Building Better Django WEB APIs with GraphQL Tutorial

Build GraphQL Web APIs with Django Graphene

GraphQL allows you to query your server for the exact data that you want ,no less no more ,sending just one request even for multiple related models .

So the first difference ,when using the classic Rest APIs ,in many situations you either get less data ,in this case you will need to send more requests to retrieve all data you need ,or you get more data than what you actually need ,which consumes your server and your network resources .

The second difference ,when requesting some model data from a Rest endpoint ,if you need the related models data you usually end up with more requests to multiple endpoints .

Thanks to GraphQL ,the client can describe and define exactly the requested data in a JSON format and the server takes care of sending the data in the same format .

Lets take a simple example to understand how GraphQL works .

Suppose we have a Django web application with two models ,products and families :

class Product(models.Model):

class Family(models.Model):

Each product belongs to a family thus they are related with a foreign key .

Now if you need to build a Rest API for this web app ,you will end up with multiple endpoints ,such as :

/products : To Get all products or add a product with HTTP GET and PUT methods . /families : To Get all families .

/product/:id : To Get or edit a product by its id . /family/:id : To Get or edit a family by its id .

Now lets say you want to get all products of a specified family ,you will need to add another endpoint .

Something like :

/family/:id/products where :id is the identifier of the family of products .

Now lets say that a request to endpoint /product/1 returns a serialized object ,like :

{
    id : 1 ,
    reference : 'PR001' , 
    name : 'Product 001' ,
    description : 'Description of Product 001' ,
    quantity : 1000
}

That's good but what if you need to build another front end app maybe for mobile devices ,remember that one of the purposes of WEB APIs is having multiple clients ,that needs only some of this data ,maybe it doesn't need the description attribute ,you have two options here :either add another endpoint or modify the existing endpoint but that's not practical in most situations because it is going to break other existing clients .

So as you can see ,in the case of classic Rest APIs ,the server API architecture is strongly coupled with the client implementation ,as a result if you need to change the API implementation on the server ,you'll definitely end up breaking the API clients . And if you need to add another client for your API ,which either does need less or more data served by each endpoint ,you'll have to change the server code responsible for serving the API in a way that doesn't break the existing clients ,that means conserving the old endpoints and adding new endpoints .

If you have ever developed an API with Django or any other framework then you certainly experienced one or all of these problems we have talked about above and thanks to Facebook developers ,GraphQL has the solutions for you .

So continuing with the example above ,in the case of GraphQL we can send a query which looks like :

query {  
product(id:1) {
    id
    reference
    quantity
}
}

Which is going to return something like :

{
    id : 1 ,
    reference : 'PR001' , 
    quantity : 1000
}

As you can see we have omitted two attributes without causing any problems or changing the underlying server API .

Just query the data you want and the server will be able to send it without any extra .

Now if you need to get all products of a specified family with GraphQL ,say for example for family with id = 1 , you can simply write :

query {  
family(id:1) {
    id
    products {
        id,    
        reference,
        name,
        description,
        quantity
    }
}
}

If you send this query to your GraphQL server ,you'll get something like :

{
"id":"1",
"products":[{"id":"1","reference":"PR001","name":"Product1","description":"..."} , ... ]
}    

Even if this example is fairly simple but you can see how powerful this new technology is ,for building Web APIs .

In the next tutorial section we are going to build a real world web application with Django and Graphene ,the Python implementation for GraphQL .

Thanks for reading and see you on the next section .


I'm a web developer and technical writer. Passionate about modern JavaScript technologies and currently trying to develop all kind of apps (Web, Mobile and Desktop) with JavaScript.