The Best Way to Expose GraphQL APIs in WSO2 API Manager 2.x Versions

Wasura Wattearachchi
Feb 28 · 9 min read
Confused?

Are you a fan of GraphQL APIs and tired of wondering how to expose a GraphQL API in WSO2 API Manager 2.x versions?

Yes, you might think we cannot do it since the GraphQL support was introduced from WSO2 API Manager 3.0.0 onwards. But what if I say, that I am going to show you how to do it using WSO2 API Manager 2.6.0?

Of course, we cannot directly expose a GraphQL API in WSO2 API Manager 2.6.0. But we can serve it as a REST API which will ultimately be a workaround that you can try. Interesting, right? Let me show you how to do this using an example with a demonstration.

Note that, you can try this out using any WSO2 API Manager 2.x version, but here, I will be using 2.6.0 for the demonstration.

I will explain the theories and the reasons behind the decisions I take throughout the demonstration. So do not think that this is only a tutorial or a how-to guide. This is more than that. Come along!!!

Do you know what GraphQL means?

GraphQL was developed by Facebook that is an alternative to REST. It can be further defined as a query language for APIs where a particular user can specify exactly what data is needed from an API during a particular API call.

We know that we can use a Swagger Definition (Open API Specification) to design a REST API. But in GraphQL, we can use Schema Definition Language (SDL) to write a schema for a GraphQL API. (To learn more about the GraphQL APIs, please refer to the links mentioned under the section References at the end of this article, which consists of an article series written by myself on the Significance of GraphQL)

In this article, we are going to invoke a GraphQL API over https/http. For this task, I am going to use the HackerNews API backend. What HackerNews normally does is, it stores the details like URLs and descriptions about particular links. Using this API you can add new links and retrieve data about the stored links.

First things First

If you are interested in trying this out you must have the following prerequisites satisfied. Otherwise, you can skip this part and follow the article to understand what I am going to show you.

Start the GraphQL API backend

You can use any GraphQL backend you like. But I will be using HackerNews API here. You can also use the same one if you want to simply try this out.

  • Open up a terminal and execute 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 start 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 the below when the GraphQL backend has started successfully.

Create and Publish a GraphQL API in WSO2 API Manager 2.6.0

The main aim of this article is to show you “How to expose a GraphQL API as a REST API in WSO2 API Manager 2.6.0?” since we do not have the support to directly expose a GraphQL API in 2.x versions. This is similar to creating and publishing a REST API in WSO2 API Manager.

1. Sign in to the Publisher portal in WSO2 API Manager.
https://<hostname>:9443/publisher (e.g:- https://localhost:9443/publisher). Use your username and password.

2. Close the interactive tutorial that starts automatically if you are a first-time user, and click ADD NEW API. Select Design a New REST API and click Start Creating.

3. Give the information according to the GraphQL API that you have. Below is an example that is used to create an API — HackerNews. After you enter the information click Add button at the bottom.

  • Name: HackerNews
  • Context: /hackernews
  • Version: 1.0.0
  • Tags: hackernews, graphql
  • URL pattern of Resources: /
  • Request types: GET, POST

Tip — To invoke a GraphQL API you can either use a GET resource or a POST resource. (Most popular way is to use POST) This is the main reason that we needed to create two (2) resources as GET and POST.

4. After you add the resource, click its GET resource to expand it.

  • Update the values for both Produces and Consumes as application/json.
  • Next, add the following parameters. (You will use these parameters to invoke the API using the integrated API Console, which will be explained later)

5. Now expand the POST resource and fill as below.

6. Once done, click Next: Implement and then click on the Managed API option. When the Implement tab opens. Enter the information in the table below.

  • Endpoint type: HTTP/REST endpoint
  • Production endpoint: http://localhost:8080 (I have given the endpoint for the GraphQL server which I have deployed) To verify the URL, click the Test button next to it (this is the actual endpoint where the API implementation can be found).
  • Sandbox endpoint: No need to provide

7. Click Next: Manage. Fill in the details as shown below.

8. Click Save & Publish.

Now you have a REST API named HackerNews which the backend points to a GraphQL API in http://localhost:8080.

Invoking the GraphQL API

Prerequisites

You need to have an Application that is subscribed to the above-created API before invoking it. (I will be using an Application named NewsApplication) Follow the steps here to create an application, to subscribe to the API and to generate the keys.

Invoking the GraphQL API to use GraphQL Mutations

1. Sign in to the WSO2 API Manager Store and click an API.

2. Navigate to the API Console tab in the particular API.

Tip— Writing data using GraphQL Mutations can only be done using POST methods.

3. Sending mutations.

  • Assume you want to send the below mutation with data.
Example :-mutation createLink {
createLink(url: "https://wso2.com", description:"WSO2 official website"){
url
Description
}
}
  • The purpose of this mutation is to create a new link with the URL: “https://wso2.com” and the description: “WSO2 official website”.
  • Expand the POST method and click on Try it out.
  • Enter the query in the payload section as shown below and click on Execute button.

The payload should look like below.

{
"query": "mutation createLink { createLink(url: \"https://wso2.com\", description:\"WSO2 official website\"){ url, description } }",
"variables": null,
"operationName": "createLink"
}
  • The response will look like below.

Now you have created a record in the database (MongoDB) using the createLink Mutation. Try adding more entries using the same method.

Invoking the GraphQL API to Fetch Data using GraphQL Queries

Sending a GraphQL query to retrieve data can be done using two (2) methods, which are either using a GET method or a POST method.

1. Sending through GET method

  • First, assume you want to send a query like the below to your GraphQL backend.
Example :-{
allLinks {
url,
description
}
}
  • The purpose of this query is to retrieve the URLs and descriptions of all the links stored in the database.
  • Expand the GET method and click on Try it out.
  • Enter the query as shown below click on Execute button.
  • The response will look like below.

2. Sending through POST method

  • You can send the same query in two (2) ways to get the response.

Method 1

  • Assume you want to send the same query which we sent earlier.
  • Expand the POST method and click on Try it out.
  • Enter the query in the payload section as shown below click on Execute button.
  • The payload should look like below
{
"query": "{ allLinks { url, description } }",
"variables": null,
"operationName": null
}
  • In here only the query is passed, nothing else. You can find more details about the syntax of the payload in Method 2.
  • The response will look like below.

Method 2

  • Assume you want to send the same query but with a different syntax as shown below.
Example :-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.
  • Expand the POST method and click on Try it out.
  • Enter the query in the payload section as shown below click on Execute button.
  • The payload should look like below
{
"query": "query links{ allLinks { url description } }",
"variables": null,
"operationName": "links"
}
  • 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.
  • The response will look like below. (which is similar to the response we got in Method 1)

Special Note

  • Assume you have a payload like below.
{
“query”: “query aTest($arg1: String!) { test(who: $arg1) }”,
“operationName”: “aTest”,
“variables”: { “arg1”: “me” }
}
  • 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 its value as “me”.

Voilà!

I think you believe now that we can serve a GraphQL API using the WSO2 API Manager 2.6.0 as well. Magnificent isn’t it?

Try using other WSO2 API Manager versions (such as 2.x and 3.x both), to check this capability further. Refer to the articles in the References section if you are interested to learn more about GraphQL.

Thank you and Goodbye! See you soon with another article…

Stay safe everyone…

References

API Integration Essentials

APIs enable connecting today’s businesses to consumers.

API Integration Essentials

APIs enable connecting today’s businesses to consumers. Read the articles in this publication to understand how APIs can facilitate your business for digital transformation.

Wasura Wattearachchi

Written by

API Integration Essentials

APIs enable connecting today’s businesses to consumers. Read the articles in this publication to understand how APIs can facilitate your business for digital transformation.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store