Chapter 2. Installing APIcast

APIcast is an NGINX based API gateway used to integrate your internal and external API services with the Red Hat 3scale API Management Platform. APIcast does load balancing by using round-robin.

In this guide you will learn about deployment options, environments provided, and how to get started.

Prerequisites

APIcast is not a standalone API gateway. It needs connection to 3scale API Manager.

To install APIcast, perform the steps outlined in the following sections:

2.1. APIcast deployment options

You can use hosted or self-managed APIcast. In both cases, APIcast must be connected to the rest of the 3scale API Management platform:

  • Embedded APIcast: Two APIcast gateways (staging and production) come by default with the 3scale API Management installation. They come pre-configured and ready to use out-of-the-box.
  • Self-managed APIcast: You can deploy APIcast wherever you want. Here are a few recommended options to deploy APIcast:

2.2. APIcast environments

By default, when you create a 3scale account, you get embedded APIcast in two different environments:

  • Staging: Intended to be used only while configuring and testing your API integration. When you have confirmed that your setup is working as expected, then you can choose to deploy it to the production environment. The OpenShift template sets the parameters of the Staging APIcast in a way that the configuration is reloaded on each API call (APICAST_CONFIGURATION_LOADER: lazy, APICAST_CONFIGURATION_CACHE: 0). It is useful to test the changes in APIcast configuration quickly.
  • Production: This environment is intended for production use. The following parameters are set for the Production APIcast in the OpenShift template: APICAST_CONFIGURATION_LOADER: boot, APICAST_CONFIGURATION_CACHE: 300. This means that the configuration will be fully loaded when APIcast is started, and will be cached for 300 seconds (5 minutes). After 5 minutes the configuration will be reloaded. This means that when you promote the configuration to production, it may take up to 5 minutes to be applied, unless you trigger a new deployment of APIcast.

2.3. Configuring the integration settings

Go to [your_API_name] > Integration > Configuration.

On the Configuration page you will see the Integration settings.

By default, you find these values:

  • Deployment Option: embedded APIcast.
  • Authentication mode: API key.

You can change these settings by clicking on edit integration settings in the upper-right corner.

2.4. Configuring your service

You must declare your API back-end in the Private Base URL field, which is the endpoint host of your API back-end. APIcast will redirect all traffic to your API back-end after all authentication, authorization, rate limits and statistics have been processed.

This section will guide you through configuring your service:

2.4.1. Declaring the API backend

Typically, the Private Base URL of your API will be something like https://api-backend.yourdomain.com:443, on the domain that you manage (yourdomain.com). For instance, if you were integrating with the Twitter API the Private Base URL would be https://api.twitter.com/.

In this example, you will use the Echo API hosted by 3scale, a simple API that accepts any path and returns information about the request (path, request parameters, headers, etc.). Its Private Base URL is https://echo-api.3scale.net:443.

Procedure

  • Test your private (unmanaged) API is working. For example, for the Echo API you can make the following call with curl command:

    curl "https://echo-api.3scale.net:443"

    You will get the following response:

    {
        "method": "GET",
        "path": "/",
        "args": "",
        "body": "",
        "headers": {
          "HTTP_VERSION": "HTTP/1.1",
          "HTTP_HOST": "echo-api.3scale.net",
          "HTTP_ACCEPT": "*/*",
          "HTTP_USER_AGENT": "curl/7.51.0",
          "HTTP_X_FORWARDED_FOR": "2.139.235.79, 10.0.103.58",
          "HTTP_X_FORWARDED_HOST": "echo-api.3scale.net",
          "HTTP_X_FORWARDED_PORT": "443",
          "HTTP_X_FORWARDED_PROTO": "https",
          "HTTP_FORWARDED": "for=10.0.103.58;host=echo-api.3scale.net;proto=https"
        },
        "uuid": "ee626b70-e928-4cb1-a1a4-348b8e361733"
      }

2.4.2. Configuring the authentication settings

You can configure authentication settings for your API in the AUTHENTICATION SETTINGS section.

The following fields are all optional:

FieldDescription

Host Header

Define a custom Host request header. This is required if your API backend only accepts traffic from a specific host.

Secret Token

Used to block direct developer requests to your API backend. Set the value of the header here, and ensure your backend only allows calls with this secret header.

Credentials location

Define whether credentials are passed as HTTP headers, query parameters or as HTTP basic authentication.

Auth user key

Set the user key associated with the credentials location

Errors

Define the response code, content type, and response body, for the following errors: authentication failed, authentication missing, no match.

2.4.3. Configuring the API test call

Procedure

  1. Configure the test call for the hosted staging environment.
  2. Enter a path existing in your API in the API test GET request field (for example, /v1/word/good.json).
  3. Save the settings by clicking on the Update Product button in the bottom right part of the page.

    1. This will deploy the APIcast configuration to the 3scale Hosted staging environment. If everything is configured correctly, the vertical line on the left should turn green.

      Note

      If you are using one of the Self-managed deployment options, save the configuration from the GUI and make sure it is pointing to your deployed API gateway by adding the correct host in the staging or production public base URL field. Before making any calls to your production gateway, do not forget to click on the Promote v.x to Production button.

  4. Find the sample curl at the bottom of the staging section and run it from the console:

    curl "https://XXX.staging.apicast.io:443/v1/word/good.json?user_key=YOUR_USER_KEY"
    Note

    You should get the same response as above, however, this time the request will go through the 3scale hosted APIcast instance. Note: You should make sure you have an application with valid credentials for the service. If you are using the default API service created on sign up to 3scale, you should already have an application. Otherwise, if you see USER_KEY or APP_ID and APP_KEY values in the test curl, you need to create an application for this service first.

    Now you have your API integrated with 3scale.

3scale Hosted APIcast gateway does the validation of the credentials and applies the rate limits that you defined for the application plan of the application. If you try to make a call without credentials, or with invalid credentials, you will see an error message.

2.5. Additional resources

To get information about the latest released and supported version of APIcast, see the articles: