The Significance of GraphQL — Part 4 (How to serve GraphQL over HTTP?)

In this article, I am going to show you “How to serve GraphQL using HTTP GET and POST methods?”. Before moving on to the discussion, you should download the demo GraphQL backend which I created using Java, from the below link. (Clone the following Git repository)

wasuradananjith/HackerNews-GraphQL-Java

Prerequisites

• I will be using Ubuntu 16.04 LTS as the OS for the demonstrations.
• Must have set up Java JDK in your machine.
• Install Maven. (https://maven.apache.org/)
• Install MongoDB. (https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/)
• Install the Postman App to demonstrate HTTP methods. (https://www.getpostman.com/)
• Clone the above Git repository to your machine.

Run and Start

• Open up a terminal and issue the following command to start mongod:

sudo service mongod start

• Navigate to the repository which you cloned from the Git, open up a terminal and type the following in order to up the GraphQL backend.

mvn jetty:run

Note — When you are running this for the first time it will take some time to start the server.

• The terminal should be like below when the GraphQL server has started successfully.

What is this HackerNews API?

• As an example for the demonstration, I am going to use the HackerNews API which has the following functionality.
• What HackerNews normally does is, it stores the details like URL, description about particular links.
• Using HackerNews API you can add new links and retrieve data about the stored links.

In here I am going to discuss, “How to use GraphQL Mutations?” and “How to fetch data using GraphQL Queries” over HTTP.

Using GraphQL Mutations

Writing data using GraphQL Mutations can be done using the POST method.

• Assume you want to send the below mutation with data.

mutation createLink {
  createLink(url: "https://medium.com", description:"Medium Website"){
    url
    Description
  }
}

• The purpose of this mutation is to create a new link with the URL: “https://medium.com” and the description: “Medium Website”.
• Open up the Postman Application.
• Select POST as the method and enter the URL http://localhost:8080/.
• Navigate to the Body tab in Postman and set as raw — JSON (application/json). Type the following as the body.

{
  "query": "mutation createLink { createLink(url: \"https://medium.com\", description:\"Medium Website\"){ url, description } }",
  "variables": null,
  "operationName": "createLink"
}

Postman interface after you enter the details correctly

• In here the query is passed, along with the operationName.
• Now click the Send button. It will give you the below result.

Result after sending the POST request

• In here what you have done is, inserted a new link to the MongoDB database which consists the URL and description as above. Likewise, you can add more links to the database.
• Add another link as below.

Send the query like above

After clicking the Send button — The result

Now you have inserted 2 records to the database. The next question is “How to retrieve them?”. In here you must use GraphQL Queries to fetch data.

Fetching Data using GraphQL Queries

Sending a GraphQL query to retrieve data can be done using 2 methods, which are either using a GET method or a POST method. Let us consider these two methods separately.

1. Fetching data through GET method

• First, assume you want to send a query like below to your GraphQL server. (when calling the GraphQL API)

{
   allLinks {
         url, 
         description
   } 
}

• The purpose of this query is to retrieve the URLs and descriptions of all the links stored in the database.
• Open up the Postman Application.
• Select GET as the method.
• Enter the URL as below.

http://localhost:8080/?query={allLinks {url,description}}

Postman interface after you enter the details correctly

• Now click the Send button. It will give you the below result.

Result after sending the GET request

• In here you can see all the links which are in the database are retrieved.

2. Fetching data through POST method

You can send the same query in 2 ways to get the response.

Method 1

• Assume you want to send the same query which we sent earlier.

{
   allLinks {
         url, 
         description
   } 
}

• The purpose of this query is to retrieve the URLs and descriptions of all the links stored in the database. (explained in the previous section too)
• Open up the Postman Application.
• Select POST as the method and enter the URL http://localhost:8080/.
• Navigate to the Body tab in Postman and set as raw — JSON (application/json). Type the following as the body.

{ 
   "query": "{ allLinks { url, description } }",
   "variables": null,
   "operationName": null
}

Postman interface after you enter the details correctly

• In here only the query is passed, nothing else. You can find more details about the syntax of the payload in Method 2.
• Now click the Send button. It will give you the below result.

Result after sending the POST request

Method 2

• Assume you want to send the same query but with different syntax.

query links {
     allLinks {
           url
           description
     }
}

• The purpose of this query is the same as the previous query we used in Method 1 which is to retrieve the URLs and descriptions of all the links stored in the database.
• Open up the Postman Application.
• Select POST as the method and enter the URL http://localhost:8080/.
• Navigate to the Body tab in Postman and set as raw — JSON (application/json). Type the following as the body.

{
    "query": "query links{ allLinks { url description } }",
    "variables": null,
    "operationName": "links"
}

Postman interface after you enter the details correctly

• In here the query is passed, along with the operationName. That is because we have given a specific name for the query as “links”. So we should pass it as the operationName. Still, we did not pass variables.
• Now click the Send button. It will give you the below result. (which is similar to the response we got in Method 1)

Result after sending the POST request

Special Note

• Assume you have a payload like below.

{
    “query”: “query aTest($arg1: String!) { test(who: $arg1) }”,
    “operationName”: “aTest”,
    “variables”: { “arg1”: “me” }
}

• In here you can see that the variables field is not null. It contains the variable $arg (which has the type string) which has passed to the query and it's valued as “me”.
• This type of queries can also exist, depending on the situation.

More Example Queries

Example 1

Query:
{
  allLinks(filter: {description_contains: "back", url_contains: "cool"}) {
    url
    description
  }
}
Payload:
{  
   "query":"{ allLinks(filter: {description_contains: \"back\", url_contains: \"cool\"}) { url, description } }",
   "variables":null,
   "operationName":null
}

Example 2

Query:
{
  allLinks(first: 1) {
    url
    description
  }
}
Payload:
{  
   "query":"{ allLinks(first: 1) { url, description } }",
   "variables":null,
   "operationName":null
}

Example 3

Query:
query links {
  allLinks(first: 1) {
    url
    description
  }
}
Payload:
{  
   "query":"query links { allLinks(first: 1) { url, description } }",
   "variables":null,
   "operationName":"links"
}

Conclusion

In this article, I discussed “How to serve GraphQL over HTTP?”.

You can find more information about GraphQL on below article.

GraphQL vs REST: A Detailed Comparison - Devathon Blog

Please find the below infographic on GraphQL vs. Rest from https://devathon.com.

This will be the last article of this series. Thank you and Goodbye until next time!

Previous Articles

The Significance of GraphQL — Part 1 (GraphQL vs. REST)

The Significance of GraphQL — Part 2 (How Facebook, Coursera and Artsy use GraphQL?)

The Significance of GraphQL - Part 3 (How Shopify, Twitter and The New York Times use GraphQL?)

📝 Read this story later in Journal.

👩‍💻 Wake up every Sunday morning to the week’s most noteworthy stories in Tech waiting in your inbox. Read the Noteworthy in Tech newsletter.