Chapter 1. Differentiate API environments

To support a formal development lifecycle for your developer community, you can provide separate staging and production environments to access your API. Differentiating the API environments minimizes the risk of use of the API when developing or testing in the production environment. This is different from managing the dev, test, stage, deploy cycle of the API itself.

There are several options to provide differentiated staging and production environments. This document describes the following two ways of providing differentiated environments:

1.1. Option 1: Staging restricts access based on rate limits or methods

The main limitation of this method is that both environments share the same backend. The production and staging traffic is mixed together and can not be distinguished in the analytics views.

Following are the high-level steps to use this option:

  1. Create one Application plan for each environment and set the rate limits and availability of methods/metrics depending on the environment (see setting rate limits). Example: in the staging mode, to provide lower rate limits and optionally restrict access to any methods that are not desirable for staging (example: expensive resources) or write/delete methods.
  2. Alternatively, enable some endpoints only in staging environment, until you are ready to make them available to everyone in production.

  3. On the integration side, implement the mapping to the corresponding 3scale methods. Note that this is only simulating environments and not hitting two different endpoints. Example: you have the following application plans on your service: "Production" and "Staging". You want to restrict the availability of endpoint GET /api/products/feed to the staging environment. In this case, you will take the following steps:

    1. Create a new metric or method "feed".
    2. Configure the following mapping rule on the Integration page: GET /api/products/feed ⇒ 'feed'.
    3. In the "Production" application plan, set limits to 0/eternity.
    4. In the "Staging" application plan, set the limits that you want to apply.

In this setup, when an application on "Production" plan tries to make a GET call to /api/products/feed, the call gets rejected. The applications on "Staging" plan can use the endpoint according to the limits, so you can test the new endpoint safely. When you are ready to enable the endpoint in the production environment, you must remove the 0/eternity limit and set the rate limits that you want.

1.2. Option 2: Using a separate API service for each environment

A common approach to differentiate the environments is to use separate API services for each environment. Example: for a "Products" service, which is the production environment, you can additionally configure "Products Dev" and "Products QA". The developers and the quality assurance team can then use these environments.

This approach has the following characteristics, which may be beneficial depending on the use case:

  • Different API backends can be used for different environments.
  • Different Public Base URLs can be used for routing to the correct service. So, you can use https://qa.api.example.com for the QA environment and https://api.example.com for production. You can also use the same endpoint and route the requests to the correct services by path, typically by adding a prefix; example: /qa/api/products/{id}, /dev/api/products/{id}, etc. To enable path-based routing ensure that you enable the environment variable APICAST_PATH_ROUTING=true in your APIcast instance.
  • In this scenario you must have a separate application for each environment because each service requires its own application. However, it is possible to use the same credentials (i.e. API key or App ID/App key) for the applications in different services. You can sync the APIcast configuration across services either on the Integration page in the admin portal or using 3scale Account Management API.