Environments and Environment Groups

If you are building or testing any non-trivial API, the requests to the API can quickly can become quite complicated. If you need to test your API in different contexts and environments, you need to keep track of and use many different values for each context. For example, even though an API in staging and production environments use similar requests, the details such as URLs, user IDs, and user keys usually differ.

Environments are a way to manage requests using variables in the requests rather than one-off hard-coded values. You use these variables in your requests for the same reasons that you use variables in programs - to reuse your work in as many contexts as possible and to avoid mistakes. An environment is a set of name/value pairs that can be used in any request in the API Project. The names in the environment are the variables in your requests and the values in the environment are the actual values that will be used in the requests.

Using a single environment

For example, you could create a simple environment named "Production" containing two name/value pairs:

To create the "Production" environment shown above, follow the following steps:

📘

To create a request, you must have an API Project. If you do not have an API Project, you can create a simple one named My API Requests (or similar) to act as your playground for playing with API Requests.

1. Navigate to https://rapidapi.com/studio or click the My APIs link in the header of the API Hub. You may need to log in before accessing it.

2. In the dropdown in the upper right, select Personal. This will display the API Projects in your Personal Account.

3. Click on the API Project that you would like to use for sending requests. If needed, you can create one by clicking Add API Project in the upper right.

4. In your API Project, in the left sidebar, click the Requests tab.

5. Expand the Environments dropdown.

6. Click the Manage Environment icon (the settings icon to the right of the +).

7. In the Environments dialog, click Add Environment Group. An environment named "New Environment" (or similar) should be created inside an Environment Group named "Group 1". Environment groups are discussed below.

8. Rename the "New Environment" environment to "Production". You can do this by double-clicking on the environment name or by hovering over the environment name, selecting the three vertical dots icon, and clicking "Rename".

9. In the Variable name column, enter "REQUEST_URL". In the Value column, enter "https://rapidapi.com" (or the URL of your choice).

10. Repeat this process and add a variable named "USER_NAME" with a value of "Test Production User".

11. Click the X in the upper right to dismiss the Environments dialog. Under Environments, you should see your "Group 1" environment group with the "Production" environment selected.

Now that we have a simple environment, any place in a request that contains a reference to the URL or user name can be replaced with the environment variable. When the request is made, the value of the environment variable is used.

In this example, instead of hard-coding the URL value, we use the REQUEST_URL environment variable. You can see a Preview of what value will be used in the current request given the currently selected environment. Here the actual value used in the request is "https://rapidapi.com".

To use a variable from your new "Production" environment, perform the following steps:

1. In the middle frame, next to the Requests label, click the + to add a new request.

2. In the URL text box to the right of the HTTP method dropdown, type a { or right-click in the text box.

3. Select Environment Variable.

4. Click Environment Variable. You should see your two environment variables created earlier.

5. Click REQUEST_URL. You should see that the text box now displays something line "Group 1 - REQUEST_URL". Also, under Preview you should see the value of the variable from the "Production" environment (notice that the "Production" environment is currently selected on the left).

6. Click Send and verify that the URL from the "REQUEST_URL" value is used for the request.

This environment variable can be used instead of hard-coding this value in any place it is used in ANY request for the API Project. This avoids the risk of accidentally mis-typing the URL value in a request. Also, if the URL value ever changes, you only have to change the value in a single place (where the environment is defined) rather than in every place that the variable is used.

Using multiple environments

Now that we have a single environment named "Production", we can duplicate that environment, change the values of the environment's variables and call it "Staging".

Now, since we have two environments, before sending a request we can select the environment that we want to use from the dropdown on the left. Changing the environment changes the values used in the request. In this case, the request URL now is "https://fakestaging.rapidapi.com".

It is now easy for us to quickly change between testing our API in our staging and production environments, without having to worry about managing the details of the request for each request in each environment.

Environment groups

Notice that when we created our environment, by default it was created inside "Group 1". This is an environment group. All environments in the Requests tab of an API Project belong to an environment group. An environment group is a set of environments that usually have the same environment variable names but different values.

Let's rename our environment group to something a bit more appropriate. Here we have changed our environment group name to "Deployment". This group represents the different deployment locations of our API.

Now when making requests, we can select our environment from the Deployment environment group. Here we have selected the Production environment. Notice the the environment variable used in the request includes the environment group name prepended to the environment's variable name (Environment group name - ENVIRONMENT VARIABLE).

In our simple example, one of our variables is USER_NAME. What if we want to test more than one user? For example, we may want to test one user who had standard rights to the API and one user who has admin rights to the API. In our simple example above, we can only test one user.

Instead of trying to add multiple users to our existing environments, we will move our USER_NAME variable to a separate environment group. Adding a new environment group is often an elegant solution when adding a new "dimension" to your API requests. Here the new dimension is that we would like to test the API using multiple users instead of one. We have create a new environment group named "User" and moved the USER_NAME variable to that environment group. Now we can add an environment for each user that we would like to test.

Now, because we have two environment groups, we see two dropdown boxes when making requests in the API Project. You use these dropdown boxes to easily change the deployment and user for your request. Here we are adding a query parameter to the request with the value of the USER_NAME variable from the User environment group.