

Create and Publish a GraphQL API¶

Follow the instructions in this tutorial to design, publish, and invoke a GraphQL API.

Note

For more information on GraphQL APIs, see Create a GraphQL API.

Step 1 - Design a GraphQL API¶

Sign in to the API Publisher Portal.

https://<hostname>:9443/publisher

Example: https://localhost:9443/publisher

Let's use admin as your username and password to sign in.
Click CREATE API and then click I Have a GraphQL SDL schema.
Import the schema 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.

Enter the GraphQL API related details and click Create.

Important

Let's use the Star Wars sample backend server as the backend for our GraphQL API.

Clone the WSO2 API Manager Samples repository.

git clone https://github.com/wso2/samples-apim

Navigate to graphql-backend directory.
Run npm install to install the necessary node modules.
Run npm start to start the server.

Once the above steps are done, the Star Wars server will be running on http://localhost:8080. We can use http://localhost:8080/graphql as the endpoint when creating the API.

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

Protocol State	Description
Name	StarWarsAPI
Context	/swapi
Version	1.0.0
Endpoint	http://localhost:8080/graphql
Business Plans	Unlimited

Optionally, modify the existing GraphQL schema definition.
1. Click Schema Definition.
2. Click DOWNLOAD DEFINITION.
  
  The existing GraphQL API schema gets downloaded.
3. Update the schema definition as required.
4. Click IMPORT DEFINITION to import the updated schema definition.
Update the GraphQL API operations as required.

Instead of resources, which get populated for REST APIs, operations get populated for GraphQL APIs.
1. Click Show More under the Operations section in the OVERVIEW page to navigate to the operations page.
2. Update the operations as required.
  
  The Publisher can add rate limiting policies, scopes, and enable/disable security for each of the GraphQL API operations.
  1. Create scopes.
    
    Repeat the following sub-steps to create two scopes named adminScope and FilmSubscriberScope.
    1. Click Scopes > ADD NEW SCOPE.
    2. Enter the required details.
      
      Note
      
      The role that you enter should be a valid role that already exists in WSO2 API Manager. Make sure to assign the role to the user.
      
      Create a role named FilmSubscriber and assign it to the admin user for this example scenario. For more information, see Adding Users and Adding User Roles.
    3. Press Enter to add each scope.
    4. Click SAVE.
  2. Define the operation level configurations.
    1. Click Operations.
    2. Click Operation Level to apply rate limiting for operations.
    3. Select a throttling policy, scope, and enable or disable security for each of the operations.
      
      Apply the adminScope and FilmSubscriberScope scopes to the allFilms and allPlanets operations, respectively.
    4. Click Save.
      
      If you check the list of scopes, it should appear as follows:

Now, you have created and configured the GraphQL API successfully.

Step 2 - Publish the GraphQL API¶

Click LIFECYCLE to navigate to the API lifecycle and click PUBLISH to publish the API to the API Developer Portal.

Step 3 - Invoke the GraphQL API¶

Sign in to the DEVELOPER PORTAL.

https://<hostname>:9443/devportal

Example: https://localhost:9443/devportal
Click on the GraphQL API.

The API overview appears.
Optionally, download the API schema if required.

Note

You can download the API schema even without signing in to the Developer Portal

Click More on the API overview page and then click GRAPHQL SCHEMA to download the API schema.
Subscribe to the API.
1. Click KEY GENERATION WIZARD.
  
  This wizard takes you through the steps of creating a new application, subscribing, generating keys, and generating an access token to invoke the API. Add the two scopes (allFilms, allPlanets) that you assigned to the operations.
  
  Note
  
  You can use any application (e.g., JWT or OAuth) to subscribe to the API.
2. Copy the authorization token that appears.
Try out the operations.
1. Click TEST to navigate to the developer console.
2. Paste the access token that you previously copied into the Access Token field.

Step 5.1 - Optionally, try out a Query operation¶

Enter the following sample payload as the StarWarsAPI request. Then click on execute button as follows.
```
query{
   human(id:1000){
      id
      name
   }
   droid(id:2000){
      name
      friends{
      name
      appearsIn
      }
   }
}
```
Note

If you are going to invoke QUERY Operation, payload should be started with 'query' keyword.

If you are going to invoke MUTATION Operation, payload should be started with 'mutation' keyword.
Click Execute.

Step 5.2 - Optionally, try out a Subscription operation¶

Important

GraphQL Subscription Operations Support Over Websockets has been introduced via an U2(Level 132)/WUM update and is effective from 26^th February 2022 (2022-02-26).

For more information on how to update using U2, see Updates 2.0 Documentation. For more information on how to update using WUM, see the documentation Using WSO2 Update Manager.

The Developer Portal's GraphQL client in the U2(Level 132)/WUM updated distribution of API-M 3.2.0 effective from 26^th February 2022 (2022-02-26), supports only graphql-transport-ws sub protocol. However, API-M Gateway supports both the graphql-transport-ws sub protocol and graphql-ws sub protocol sub protocol.

Enter the following sample payload as the StarWarsAPI reviewAdded subscription request to get real-time updates about the addition of new reviews.
```
subscription {
   reviewAdded(episode: JEDI) {
      stars
      episode
      commentary
   }
}
```
Note

If you are going to invoke SUBSCRIPTION operation, you should start the payload with the keyword subscription.
Prepare to inspect the network calls from your browser developer tools.

For example, if you are using the Google Chrome browser.
1. Right-click on the browser and click Inspect.
2. Click Network to view the network calls via the browser developer tools.
Click Execute.

If you inspect the network calls from your browser developer tools, you can see the messages passed between the GraphiQL client and the backend.

As you can see, a successful WebSocket connection is established between the client and backend via WSO2 API Gateway.

While keeping the Developer Portal web browser page opened, separately open a terminal and directly invoke the backend API’s createReview mutation operation by executing the following command.

curl -X POST "http://localhost:8080/graphql" -H  "accept: application/json" -H  "Content-Type: application/json" -d '{"query":"mutation {createReview(episode: JEDI, review: { stars: 3, commentary: \"Excellent\"}) { stars   episode   commentary }}","variables":null}' -k

When the mutation is successful, the GraphQL backend will send the following response:

{"data":{"createReview":{"stars":3,"episode":"JEDI","commentary":"Excellent"}}}

Now go back to the Developer Portal browser page.

You can see that you have received the subscription event response that corresponds to the mutation operation you did in Step 5.2 (4).

You have successfully created and published your first GraphQL API, subscribed to it, obtained an access token for testing and tested your API with the access token.

Top