Create and Publish a GraphQL API

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


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

Step 1 - Design a GraphQL API

  1. Sign in to the API Publisher Portal.


    Example: https://localhost:9443/publisher

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

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

    Create GraphQL Schema Option

  3. Import the schema and click Next.

    Import a graphQL schema by adding a file

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


    • 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.

    Import a graphQL schema by adding a file

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


    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
    • 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









    Add GraphQL API details

  5. Optionally, modify the existing GraphQL schema definition.

    1. Click Schema Definition.


      The existing GraphQL API schema gets downloaded.

      Add schema definition

    3. Update the schema definition as required.

    4. Click IMPORT DEFINITION to import the updated schema definition.

  6. 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.

      GraphQL API operations

    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.

          Add a scope page

        2. Enter the required details.


          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.

          Create a scope

        3. Press Enter to add each role.

        4. Click SAVE.

          List of added scopes

      2. Define the operation level configurations.

        1. Click Operations.

        2. Click Operation Level to apply rate limiting for operations.

          Update GraphQL API 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 allCharacters and allDroids operations, respectively.

        4. Click Save.

          If you check the list of scopes, it should appear as follows:

          Scope list

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

Step 2 - Deploy and Publish the GraphQL API

  1. Click DEPLOYMENTS to navigate to the API deployments and click Deploy to deploy the API to the default gateway.

    Deploy GraphQL API

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

    Publish GraphQL API

Step 3 - Invoke the GraphQL API

  1. Sign in to the DEVELOPER PORTAL.


    Example: https://localhost:9443/devportal

    Developer Portal

  2. Click on the GraphQL API.

    The API overview appears.

    StarWarsAPI API overview

  3. Optionally, download the API schema if required.


    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.

    Download GraphQL API schema

  4. Subscribe to the API.

    1. Click TRY OUT.

      Try Out Wizard

      This will create a subscription for DefaultApplication and generate consumer key, consumer secret pair for the DefaultApplication. Click TRY OUT on the pop-up window to navigate to the try-out console.

      Try Out Popup

  5. Try out the operations.

    1. Click GET TEST KEY.

      Get Test Key

    2. Enter the following sample payload as the StarWarsAPI request. Then click on execute button as follows.


      Execute GraphQL Query


      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.

    3. Click Execute.

      Response of GraphQL Query

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.