Overview

GraphQL APIs have a different architectural style than other common types of APIs, such as REST APIs. For example, a GraphQL API typically has a single HTTP POST endpoint, and the body of the request defines the specifics of the query (reading data) or mutation (changing data). Because of this, Rapid offers a unique API consumer experience for GraphQL APIs.

In Rapid, GraphQL APIs use an editor based on an industry-standard editor named GraphiQL. This editor has been customized and enhanced to work well with GraphQL APIs on Rapid.

To effectively work with GraphQL API queries, it is suggested that you click the icon on the right of the center bar to use more of your screen for queries, as shown below.

Each of the three main frames (left, center, and right) shown above is described below.

Left frame

The left frame has three modes:

• Explorer - Uses an easy-to-use user interface to help create queries and mutations for the API.
• History - A list of queries or mutations you have made for the API.
• Docs - Used to browse and navigate the schema documentation for the API.

Left frame - Explorer mode

Click the left icon in the left frame to access the Explorer mode for building queries and mutations. To build a query, simply click on a query or mutation on the left and you will see the query editor in the Query tab in the center begin to populate. For example, the screenshot below shows the query that is starting to be built by clicking the allFilms query.

Notice the the query editor underlines allFilms, indicating that the allFilms query is not complete enough to execute successfully. You can hover over allFilms to see information to help complete the query.

Multiple queries per operation

If your API supports multiple queries (or mutations) per operation, you can build these operations in Explorer mode. This is sometimes known as "query batching".

The Explorer frame can contain one or more operation. For example, an operation named MyQuery is shown below. If you click on a query under the MyQuery operation, it will be added inside the operation. In the example below, we have clicked on both countries and continents queries under the MyQuery operation. In the query editor, you can see both the of these queries in the operation. Executing this query returns results in both a countries object and a continents object.

Multiple operations per execution

You can execute multiple operations in a single execution by using the Add new dropdown in the upper part of the left frame. Each operation is uniquely named, and has a complete set of user interface elements to choose from.

In the example below, we added a new query named MyQuery2. Clicking the execute button executes both operations, in this case displaying continents using MyQuery1 and countries using MyQuery2.

If you hover over the name of the operation in Explorer view, you will see two icons (as shown below).

• Click the trash icon to delete the operation.
• Click the second icon to copy the operation. It will be created at the bottom of the Explorer view with a name like MyQueryCopy. You will also see the copied operation in the query editor in the middle frame.

Left frame - History mode

Clicking the history icon in the left frame (the second icon at the top of the left frame below) displays a list of previous queries you have executed for the API (if any). This list is automatically populated as you execute queries (or mutations). In this mode, you can perform the following actions:

• Click on an operation in the history list to display the operation in the query editor in the middle frame. This will replace any previous operation in the query editor. The operation name is displayed in the list. For example, in the screenshot below, the operation is of type query and is named myPing. If the operation is not named, the first portion of the query is displayed (for example, in. the last query of the list below). The name in the History list can be changed by clicking the pencil icon next to the operation (see the first of three icons outlined below). Changing the name in the history list will not change the operation name in the query editor.
• Click the Clear button to the right of the History label to clear the history list.
• Click the pencil icon next to the query (see the first of three icons outlined below) to change the name of the operation in the history list. Changing the name in the history list will not change the operation name in the query editor. However, changing the name of the operation in the query editor of the middle frame will change the name of the operation in history, so this is the recommended way to change the operation name.
• Click the star icon next to the query (see the second of three icons outlined below) to mark the operation as a favorite. This will move and stick the operation to the top of the history list, as shown with the myPing operation below.
• Click the recycle icon next to the operation (see the third of three icons outlined below) to delete the operation from the history list.

📘

History limitations

The history list is stored in a browser cookie. This means that the history is only applicable for the current browser. For example, if you opened an incognito browser window and logged in as the same user, the same history will not be shown (the history would be empty).

Only the query and variables are saved in history. Other values such as context, headers, and files are not saved in the history.

Left frame - Docs mode

Clicking the Docs icon in the left frame (the third icon at the top of the screenshot below) displays a linkable version of API's GraphQL schema.

You can click the search icon in the upper right (or press CTRL K) to search the schema. The field names and types are clickable, so that you can view more information about the query. In the example below, we could click on the countries field to explore it further, or directly click on the CountryFilterInput argument type or Country return type to view their details.

Note that navigating in docs mode does not change the query in the query editor of the middle frame. However, Explorer mode (the left icon at the top) does this.

Center frame

The center frame has four main tabs and one execution button:

• Context tab
• Headers tab
• Query tab
  • Query editor
  • Variables tab
  • Files tab
• Authorization tab
• Execution icon

Center frame - Context tab

The Context tab is where you select the user or team that will execute the query. This changes the Rapid API keys that will be used (on the Headers tab) and is important for accurately reporting which user or team made the query.

If your user or team has multiple apps, select the correct app in the Apps dropdown.

If you are an Enterprise Hub user and you have configured API Gateways, select the gateway in the Request URL. Otherwise, select rapidapi.com, and the Rapid Runtime will be used when testing the API.

Center frame - Headers tab

The Headers tab is where you can set required and optional request headers for the API. In some case, these values will be filled in for you. For example, in the screenshot below, the Authorization headers is populated with a Base64 value resulting from entering the user and password on the Authorization tab (see the Authorization tab below).

Center frame - Query tab

Query editor

The top area Query tab displays the query editor. This is a text are that displays the query or mutation that will be executed if you click the execution icon (explained below). It also contains the text that will be included in any Code Snippets in the right frame.

There are three main ways to populate the text of the query editor

1. Paste an existing query. For example, from a tutorial. This query can be modified using either of the approaches below.
2. Build or modify a query graphically using the Explorer mode in the left frame.
3. Type the query or mutation manually, taking advantage of the intelligent graphQL editor. You can type Ctrl-Space or just start typing to take advantage of auto complete.

The Query tab has three action icons on the right:

• Prettify query
• Merge fragments into query
• Copy query

Variables tab

If your query or mutation uses variables, click the Variables tab and enter the JSON object. In the example below, the id value is passed in as a variable.

Files tab

The Files tab is used if you are calling a mutation that includes a file upload. Click the Files tab, then the plus sign to browse to a local file. In the path to variable textbox (the top highlighted box in the screenshot below), specify the path to the location of the file as defined in the Variables. In the screenshot below, the mutation expects the file to be located in the spec field of theupdates object (updates.spec).

Center frame - Authorization tab

The Authorization tab is only visible if your API uses authorization (security schemes) in addition to the Rapid authorization.

In the example below, we have set up HTTP Basic authentication on our API.

Center frame - Execution icon

The icon in the upper right is used to execute the query. The icon is a right-facing triangle (see screenshot below) if you have subscribed to a plan for the API. Clicking this icon executes the query.

📘

Keyboard shortcut

You can press Ctrl-Enter to execute the query or mutation.

If you have not subscribed to a plan for the API, the icon looks like the icon in the screenshot below.

Clicking this icon will take you to the Pricing tab, where you can subscribe to a plan.

After subscribing to a plan for the API, you can navigate back to the Endpoints tab and execute the query.

Right frame

The right frame has three tabs:

• Code Snippets tab
• Example Responses tab
• Results tab

Right frame - Code Snippets tab

When you have configured your query, you can view the corresponding code in the programming language of your choice using the Code Snippets tab. Code snippets are useful for getting the query working properly in your application.

Select your language of choice in the Target dropdown. Select your library of choice in the Client dropdown. Click the copy icon on the right to copy the code to your clipboard.

The values you select for Target and Client will be saved and used the next time you execute a query.

Right frame - Example Responses tab

If the API builder has configured example responses for the endpoint, you will see an Example Responses tab, allowing you to view details similar to expected responses. This is useful if you have not yet executed the query to help understand what is expected.

Right frame - Results tab

The Results tab includes the HTTP status of the query (in the screenshot below, it is 200 OK as well as three sub-tabs.

The Info sub-tab displays basic information about the request, as shown below.

The Request sub-tab shows details of the request. You can click on the Headers tab to view the request headers. Click Text to view the body of the request as text. Click JSON to view the body of the request as JSON. Click Raw to view the full text-based HTTP request (as shown in the screenshot below).

The Response sub-tab shows details of the response. Click the Headers tab to see the response headers. Click the Text tab to see the response body as text. Click the JSON tab to see the response body as JSON (this will be the default tab if the response is JSON, otherwise the default tab is the Text tab). Click the Raw tab to view the full text-based HTTP response.