

Deploying a GraphQL API in Choreo Connect

GraphQL is a querying language for APIs that was initially developed by Facebook. When compared to the REST APIs, GraphQL APIs allow you to query only the required data. Response will have only the data you requested (over-fetching and under-fetching will not happen). Using a single request you can fetch data related to multiple resources. This is not possible with REST APIs. If REST API is used, you will have to consider multiple requests to gather the same amount of data. GraphQL APIs are based on a strong type system. Schema Definition Language (SDL) file defines the contract between client and the server. It explains how client can access the data provided by the server. This page explains how to deploy a GraphQL API in Choero Connect and also explains the supported features of Choreo Connect for GraphQL APIs.

Update Level 5

This feature is available only as an update, after Update level 1.1.0.5 (released on 15 Aug 2022) and further. For more information regarding Choreo Connect updates, see here.

Choreo Connect supports the below features in addition to the basic GraphQL API invocations.

• Runtime configurations
  • Transport level security
  • GraphQL query analysis (query complexity and query depth limitation)
  • Cross-Origin Resource Sharing (CORS)
• Rate limiting policies (API level and operation level) with the support of WSO2 API-M
• Security scopes
• Enable/ disable security for GraphQL operations

Note

Currently Choreo Connect supports query and mutation GraphQL operations only.

You can deploy GraphQL APIs using Choreo Connect by following one of the two deployment modes described below.

Mode	Method
Choreo Connect with WSO2 API Manager as a Control Plane	Via WSO2 API Manager Publisher Portal
Choreo Connect as a Standalone Gateway	Via apictl for Standalone Mode

Via WSO2 API Manager Publisher Portal

Below instructions explain how to deploy a GraphQL API to Choreo Connect via the Publisher Portal in WSO2 API Manager.

Before you begin

• This guide assumes that you already have an up and running Choreo Connect instance configured with WSO2 API Manager. If not, you can refer to the Quick Start Guide on how to run Choreo Connect with WSO2 API Manager. To learn more about Choreo Connect related components, refer to the Overview of Choreo Connect.
• GraphQL schema file (SDL) and a GraphQL server implementaion relevant to the SDL.
• You need to have a GraphQL schema file (SDL) and a GraphQL server implementaion relevant to the SDL. You can obtain the SDL file relevant to this example from here and the server implementation relevant to that SDL available in here.

Step 1 - Create a GraphQL API in WSO2 API Manager Publisher Portal

You can create a GraphQL API in WSO2 API-M Publisher Portal by following the steps described below.

1. Sign in to the API Publisher Portal.

   https://<hostname>:9443/publisher

   Example: https://localhost:9443/publisher

   Let's use admin as the username and password to sign in.

2. Click Create API and then click Import GraphQL SDL.

   

3. Import the schema by dragging and dropping the file or by uploading the file, and click Next.

   Let's use the StarWarsAPI schema definition to create the schema file.

   Note

   • You need to define the SDL Schema based on the GraphQL schema design best practices.

   • The file extension can be either .graphql, .txt, or .json.
   • The file name can be any name, which is based on your preference.

   

4. Enter the GraphQL API related details and click Create.

   Let's create an API named "StarWarsAPI" using the following sample data.

   Field	Description
   Name	StarWarsAPI
   Context	/swapi
   Version	1.0.0
   Endpoint	http://hostName:8080/graphql

   

5. Click Create button.

Step 2 - Deploy and publish the API

1. Navigate to Deploy and click Deployments to retrieve the API deployment page.

2. Click Deploy to deploy the API in Choreo Connect.

   

   The Deployment page appears.

   

3. Navigate to Publish and click Lifecycle.

   The API lifecycle page appears.

4. Click Publish to publish the API to the API Developer Portal.

   

Step 3 - Generate an Access Token to invoke the API

1. Click View in Dev Portal at the top right corner to open Developer Portal in another browser tab.

2. Open Applications from the top menu and select DefaultApplication from the list.

3. Open the Subscriptions tab and subscribe your API to the DefaultApplication.

4. Open APIs from the top menu and select your API.

5. Open the Try Out tab and click GET TEST KEY. This will include the access token in the cURL command you generate in the section below.

Step 4 - Invoke the API by providing a valid GraphQL query

1. Since GraphQL APIs require a GraphQL query to provide results, you need to have a valid query. A sample query is provided in the below section. In API Manager Publisher Portal, GraphQL is used for build queries. You can use the explorer option available there to build queries. For more information regarding valid GraphQL query generation, see here.

   query{
   human(id:1000){
       id
       name
   }
   droid(id:2000){
       name
       friends{
           name
           appearsIn
       }
   }
   }

2. Click Execute.

   You will get a response for the GraphQL API invocation, as shown below.

   

Via apictl for Standalone Mode

The CLI tool (apictl) does not support initializing projects for GraphQL APIs yet. However, you can download the sample GraphQL API project from here and try it out by deploying it into Choreo Connect. When you are using your own GraphQL API with Choreo Connect, you can change the relevant attribute values in api.yaml, graphql-complexity.yaml and definitions/schema.graphql files. There is an explanation regarding those attribute values in here.

The following steps describe how to deploy a GraphQL API in Choreo Connect standalone mode.

Step 1 - Create an API Project

When using GraphQL APIs in Choreo Connect standalone mode, you need to have an API project. The structure of a sample GraphQL API project is included below.

.
├── Definitions
│   ├── graphql-complexity.yaml
│   └── schema.graphql
└── api.yaml

Note

• Similar to the sample project, you can deploy your own GraphQL API in Choreo Connect by changing the relevant attribute values that are defined in the api.yaml file.
• graphql-complexity.yaml is an optional file where you can define complexities relevant to the GraphQL queries.

Step 2 - Add a Choreo Connect Environment to apictl

To use apictl with Choreo Connect, a Choreo Connect environment needs to be added to the apictl. This environment will hold the Adapter URL for further commands.

apictl mg add env dev --adapter https://localhost:9843

Info

The apictl commands that starts as apictl mg are Choreo Connect specific. If a command does not have mg after apictl then the command could probably be common to both Choreo Connect and API Manager, but it could also be API Manager specific.

Tip

The apictl commands here onwards are executed with the -k flag to avoid SSL verification with the Choreo Connect.

To communicate via HTTPS without skipping SSL verification (without -k flag), add the cert in the Choreo Connect truststore into the <USER_HOME>/.wso2apictl/certs folder.

Step 3 - Log in to the Choreo Connect Environment in apictl

You can use the following command to log in to the above Choreo Connect cluster (log in to the Choreo Connect Adapter). When you log in, an access token will be retrieved from Choreo Connect and it will be saved in apictl.

Format

apictl mg login dev -u <username> -p <password> -k

Example

apictl mg login dev -u admin -p admin -k

Step 4 - Deploy the API

Now let's deploy the API to Choreo Connect by executing the following command.

apictl mg deploy api -f <path_to_the_API_project_just_created>/<gqlProjectName> -e dev -k

Step 5 - Generate an access token

After exposing the GraphQL API via Choreo Connect, you can invoke an API with a valid access token.

Let's use the following command to generate a JWT to access the API, and set it to the variable TOKEN.

Format

TOKEN=$(curl -X POST "https://<hostname>:<port>/testkey" -d "scope=<scope values>" -H "Authorization: Basic base64(username:password)" -k -v)

Example

TOKEN=$(curl -X POST "https://localhost:9095/testkey" -d "" -H "Authorization: Basic YWRtaW46YWRtaW4=" -k -v)

Step 6 - Invoke the API

Note

• Choreo Connect handles GraphQL API requests considering the POST HTTP method type only. Therefore, the query given in the request should follow the JSON structure explained here.
• The request should include one of the HTTP request Content-Type headers listed below.
  • -H "Content-Type: application/json"
  • -H "Content-Type: application/graphql"

• Invoke the API using the following cURL command structure.

  Format

  curl -X POST "<Docker-hostname>:<Docker-port>/<API-context>/<API-version>" -H "Authorization: Bearer $TOKEN" -d "<query>" -H "Content-Type: application/json" -k 

  Example

  curl -X POST "https://localhost:9095/starwars/1.0.0" -H "Authorization: Bearer $TOKEN" -d '{"query":"query MyQuery { allDroids { appearsIn } }","variables":null}' -H "Content-Type: application/json" -k 

  Response

  {"data":{"allDroids":[{"appearsIn":["NEWHOPE","EMPIRE","JEDI"]},{"appearsIn":["NEWHOPE","EMPIRE","JEDI"]}]}}

Top