Into the Unknown: Developer First GraphQL APIs with APICTL 4.0.x

WSO2 API Controller 4.0.x + WSO2 API Manager 4.0.0

“Into the unknown”

Pop Quiz!

Are you looking for a way to use the Dev First appraoch of WSO2 API Controller (apictl) to create GraphQL APIs?

Dev First approach is one of the popular methods of initializing API projects and importing them to different WSO2 API Manager (WSO2 API-M) environments. Of course, if you are an apictl fan, you already know that. But, you can only create REST APIs using that method, isn’t it?

What if you want to create a GraphQL API using that approach…? Any thoughts?

The answer to the above question might be unknown for now. But, after reading this it will be known to all of you. So, follow me into the unknown!

A Glance at GraphQL…

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)

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.

Under the assumption that you have already installed Oracle Java SE Development Kit (JDK) version 11.\* and set the JAVA_HOME environment variable (For more information on setting the JAVA_HOME environment variable for different operating systems, see Setup and Install) you need to satisfy the below requirements.

• Download and set up WSO2 API-M 4.0.0 (I will be using a U2 updated API-M 4.0.0 pack for the demonstration. For more information on how to update using U2, see Updates 2.0 Documentation.)
• Start WSO2 API-M 4.0.0 server
• Download and initialize apictl 4.0.x (Make sure to add an environment named “production”, since I will be using it during the demonstration)
• Setup the Star Wars sample GraphQL backend server as mentioned in the section Design a GraphQL API -> Step 4 (Refer to the Important section here)

We are all set… Are you ready to journey into the unknown?

Importing GraphQL APIs via Dev First approach

You need to follow four (4) simple steps in order to discover the unknown.

1. Initialize a GraphQL API using apictl init
2. Add the GraphQL schema definition
3. Edit the necessary fields in the API definition
4. Import the API to the WSO2 API-M environment

Step 1 — Initialize a GraphQL API using apictl init

Execute ./apictl init <your-project-name> as shown below.

This command will create an API project with the below structure.

TestAPI
├── api_meta.yaml
├── api.yaml
├── Client-certificates
├── Definitions
│   └── swagger.yaml
├── deployment_environments.yaml
├── Docs
├── Image
├── Interceptors
├── libs
├── README.md
└── Sequences
    ├── fault-sequence
    ├── in-sequence
    └── out-sequence

Step 2 — Add the GraphQL schema definition

Navigate to the Definitions directory and remove the swagger.yaml file.

The reason to remove the swagger.yamlis that you do not need to have a swagger definition for a GraphQL API in apictl 4.0.x versions. You only need to have a syntactically correct GraphQL schema.

Now, you need to add the GraphQL schema definition to the Definitions directory. Make sure to rename the schema as schema.graphql . (I will be using the schema here which WSO2 official documentation uses for GraphQL related tasks). The project structure will look like below after adding the schema definition.

TestAPI
├── api_meta.yaml
├── api.yaml
├── Client-certificates
├── Definitions
│   └── schema.graphql
├── deployment_environments.yaml
├── Docs
├── Image
├── Interceptors
├── libs
├── README.md
└── Sequences
    ├── fault-sequence
    ├── in-sequence
    └── out-sequence

Step 3 — Edit the necessary fields in the API definition

This is the most important step that we need to remember. We need to edit the API definition file (api.yaml).

• First, open the api.yaml file in a text editor. It will initially look like below

type: api
version: v4.0.0
data:
  version: 1.0.0
  provider: admin
  lifeCycleStatus: CREATED
  isRevision: false
  revisionId: 0
  type: HTTP
  transport:
  - http
  - https
  policies:
  - Unlimited
  visibility: PUBLIC
  endpointConfig:
    endpoint_type: http
    production_endpoints:
      url: http://localhost:8080
    sandbox_endpoints:
      url: http://localhost:8081
  endpointImplementationType: ENDPOINT
  websubSubscriptionConfiguration: null

• Make sure to add the fields name and the context to the definition with the values of your choice.

type: api
version: v4.0.0
data:
  name: TestAPI
  context: /testapi
  version: 1.0.0
  provider: admin
  lifeCycleStatus: CREATED
  isRevision: false
  revisionId: 0
  type: HTTP
  transport:
  - http
  - https
  policies:
  - Unlimited
  visibility: PUBLIC
  endpointConfig:
    endpoint_type: http
    production_endpoints:
      url: http://localhost:8080
    sandbox_endpoints:
      url: http://localhost:8081
  endpointImplementationType: ENDPOINT
  websubSubscriptionConfiguration: null

• Now, edit the endpointConfig to have valid Production and Sandbox endpoint URLs (Later we can use this endpoint to do GraphQL invocations). I will be using the endpoint (http://localhost:8080/graphql) in Create a GraphQL API page in the official WSO2 API-M documentation.

type: api
version: v4.0.0
data:
  name: TestAPI
  context: /testapi
  version: 1.0.0
  provider: admin
  lifeCycleStatus: CREATED
  isRevision: false
  revisionId: 0
  type: HTTP
  transport:
  - http
  - https
  policies:
  - Unlimited
  visibility: PUBLIC
  endpointConfig:
    endpoint_type: http
    production_endpoints:
      url: http://localhost:8080/graphql
    sandbox_endpoints:
      url: http://localhost:8080/graphql
  endpointImplementationType: ENDPOINT
  websubSubscriptionConfiguration: null

• Change the type field of the API to GRAPHQL as shown below.

type: api
version: v4.0.0
data:
  name: TestAPI
  context: /testapi
  version: 1.0.0
  provider: admin
  lifeCycleStatus: CREATED
  isRevision: false
  revisionId: 0
  type: GRAPHQL
  transport:
  - http
  - https
  policies:
  - Unlimited
  visibility: PUBLIC
  endpointConfig:
    endpoint_type: http
    production_endpoints:
      url: http://localhost:8080/graphql
    sandbox_endpoints:
      url: http://localhost:8080/graphql
  endpointImplementationType: ENDPOINT
  websubSubscriptionConfiguration: null

• Optionally, you can change the lifeCycleStatus as well. You can notice that the TestAPI repository has the deployment environments related information inside the file named deployment_environments.yaml. So, if we make the lifeCycleStatus to PUBLISHED , after importing the API it will get automatically published as well as deployed. Hence, I am changing the lifeCycleStatus to PUBLISHED , but it is completely your choice to decide whether to change the status or not. You can find the final api.yaml content below after doing all the changes (The changes are in bold letters).

type: api
version: v4.0.0
data:
  name: TestAPI
  context: /testapi
  version: 1.0.0
  provider: admin
  lifeCycleStatus: PUBLISHED
  isRevision: false
  revisionId: 0
  type: GRAPHQL
  transport:
  - http
  - https
  policies:
  - Unlimited
  visibility: PUBLIC
  endpointConfig:
    endpoint_type: http
    production_endpoints:
      url: http://localhost:8080/graphql
    sandbox_endpoints:
      url: http://localhost:8080/graphql
  endpointImplementationType: ENDPOINT
  websubSubscriptionConfiguration: null

Step 4— Import the API to the WSO2 API-M environment

Now, you need to import the API to the WSO2 API-M using the apictl import api command as shown below.

If you log in to the Publisher Portal of WSO2 API-M, you can see the imported GraphQL API as shown below.

Imported GraphQL API

If you check the API Overview by clicking the particular API, you can see that the API has been Published and Deployed as well.

API Overview page

Now, you can invoke the imported GraphQL API using the integrated GraphQL console as mentioned here. Try it…

Voilà!

You have uncovered the truth about the Dev First Approach for GraphQL APIs. It is not yet an unknown thing.

You can try discovering the Dev First Approach for other types of APIs as well, such as Async APIs and SOAP APIs and SOAP To REST APIs. Give it a try!!!

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

Stay safe everyone…

References

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?)

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