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.

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

--

--

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