Create your first GraphQL API

Creating a GraphQL API

API Gateway provides the ability to view, create, and manage GraphQL APIs, and publish the APIs to a configured destination for consumption. API Gateway supports proxying an existing GraphQL API endpoint and provides API management capabilities to clients like authentication and analytics. This section describes how you can create your first GraphQL API in API Gateway.

Creating GraphQL API in API Gateway

In API Gateway, you can create GraphQL APIs by importing it in two ways:

• Importing an API from URL
• Importing an API from a file

Creating a GraphQL API by Importing an API from URL

Before you begin

Ensure that you have

• Manage APIs or Activate/Deactivate APIs functional privilege.

  Note

  If you are an Administrator, you would have this privilege.

• You must have a GraphQL API base URL to create an API using the importer. For example, you can use the Star Wars base URL.

To create a GraphQL API by importing an API from URL

Let’s look at a sample scenario, where you are creating a GraphQL API, Star Wars API, by importing an API from URL.

1. Click APIs in the title navigation bar.
   A list of available APIs appears.

2. Click Create API.

3. Select Import API from URL.

4. Type the URL from where the API is imported. For example, use the Star Wars base URL.

5. Select Protected to make the API a protected API and provide the Username and Password.

6. Provide a description for the API in the Description field.

7. Type a name for the API name in the Name field. For example, Starwars_GraphQL_URL.

8. Select GraphQL SDL from the Type dropdown menu.

9. Provide a version for the API in the Version field.

10. From the Team drop-down list, select the teams that you want to assign the API to. For this use case, select Administrator.

    

11. Click Create.
    A GraphQL API is created with the default Straight Through Routing policy.

    Note

    For the API to work, you must replace the Endpoint URI of the default Straight Through Routing policy with the query string of the native API.

12. Click Edit to replace the Endpoint URI of the Straight Through Routing policy.

13. Navigate to Policies > Routing > Straight Through Routing and replace the ${sys:query_string} alias in the Endpoint URI with the query string of the native API.
    For example, use the native API endpoint of the Star Wars API,that is, https://swapi-graphql.netlify.app/.netlify/functions/index.

14. Click Activate.

15. Click Yes in the confirmation dialog box.
    The API is now activated. The API Gateway endpoint is now available, and consumers can use this endpoint to invoke the API.

Next steps

• Assess the GraphQL API created is working as expected using Postman. For more information, see Testing GraphQL API using Postman?
• If the GraphQL API is working as expected, you can publish the API to the required destination and expose the API for consumption by the consumers.

Creating a GraphQL API by Importing an API from a File

Before you begin

Ensure that you have

• Manage APIs or Activate/Deactivate APIs functional privilege.

  Note

  If you are an Administrator, you would have this privilege.

• You must have a GraphQL SDL (GraphQL Schema Definition Language) file to create an API using the importer. You can download the Starwars.graphql from the Github repository.

To create a GraphQL API by importing an API from a file

Let’s look at a sample scenario, where you are creating a GraphQL API, Star Wars API, by importing an API from from the Starwars.graphql file.

1. Click APIs in the title navigation bar.
   A list of available APIs appears.

2. Click Create API.

3. Select Import API from file.

4. Click Browse to select a file.

5. Select the required file and click Open. For example, choose the Starwars.graphql file that you downloaded from the Github repository.

6. Type a name for the API name in the Name field. For example, Starwars_GraphQL_file.

7. Provide a description for the API in the Description field.

8. Select GraphQL SDL from the Type dropdown menu.

9. Provide a version for the API in the Version field.

10. Select the team to which the API must be assigned in the Team field.

    

11. Click Create.
    A GraphQL API is created with the default Straight Through Routing policy.

    Note

    For the API to work, you must replace the Endpoint URI of the default Straight Through Routing policy with the query string of the native API.

12. Click Edit to replace the Endpoint URI of the Straight Through Routing policy.

13. Navigate to Policies > Routing > Straight Through Routing and replace the ${sys:query_string} alias in the Endpoint URI with the query string of the native API.
    For example, use the native API endpoint of the Star Wars API, that is, https://swapi-graphql.netlify.app/.netlify/functions/index.

14. Click Activate.

15. Click Yes in the confirmation dialog box.
    The API is now activated. The API Gateway endpoint is now available, and consumers can use this endpoint to invoke the API.

Next steps

• Assess the GraphQL API created is working as expected using Postman. For more information, see Testing GraphQL API using Postman?
• If the GraphQL API is working as expected, you can publish the API to the required destination and expose the API for consumption by the consumers.

Testing a GraphQL API using Postman

Before you begin

Ensure that you have

• Postman installed in your system, or you can you use the web version of Postman.
• Downloaded the sample Star Wars Postman collection (GraphQL.postman_collection.json) from the Github repository.

You must assess the GraphQL API created is working as expected before exposing it to the API consumers. You should verify the correct status code of the response. For instance, successful HTTP requests should return 200 OK, creating a resource should return 201 CREATED, and so on.

Let’s test the Starwars GraphQL API, which was imported using a file. In this example, to test whether the Star Wars API is created successfully, let’s retrieve all the films in the Star Wars franchise using the Starwars API. The API response should list all the films in the Star Wars franchise.

To test the GraphQL API using Postman

1. Open Postman.

2. Click Import.
   To Import the sample Star Wars Postman collection (GraphQL.postman_collection.json) downloaded from the Github repository.
   

   

3. Select GraphQL and select the GraphQL.postman_collection.json file from your local folder.

4. Click Import.

5. Open the imported GraphQL API collections. Select Starwars API GW.

   

6. Select a method. For example, select the method as POST.

7. Specify the request URL. For example, you can provide the Star Wars endpoint from the API you created earlier.

   

8. Set the request body type as GraphQL.

   

9. Pass the query in the QUERY section. For example, write a query to fetch a list of all the films in the Star Wars franchise.

   

10. Click Send.
    200 OK HTTP Status is displayed. The response lists all the films in the Star Wars franchise.

    

    The API is tested and working as expected. You can now expose the API to the consumers.