Using the Developer Portal

Navigate to [your_API_name] → ActiveDocs in your Admin Portal. This will lead you to the list of your service specifications for your API (initially empty).

You can add as many service specifications as you want. Typically, each service specification corresponds to one of your APIs. For example, 3scale has specifications for each 3scale API, such as Service Management, Account Management, Analytics, and Billing.

When you add a new service spec, you will have to provide:

The API JSON specification is the "secret ingredient" of ActiveDocs.

You must generate the specification of your API according to the specification proposed by OpenAPI Specification (OAS). In this tutorial we assume that you already have a valid OpenAPI Specification (OAS) 2.0-compliant specification of your API.

Once you have added your first ActiveDoc, you can see it listed in [your_API_name] → ActiveDocs. You can edit it as necessary, delete it, or switch it from public to private. You can also detach it from your API or attach it to any other API. You can see all your ActiveDocs (attached to an API or not) in Audience → Developer Portal → ActiveDocs

You can also preview what your ActiveDocs looks like by clicking on the name you gave the service specification (in the example it was called it Pet Store). You can do this even if the specification is not public yet.

This is what your ActiveDoc will look like:

3scale ActiveDocs are based on the specification of RESTful web services called Swagger (from Wordnik). This example is based on the Extended OpenAPi SpecificationPetstore example and draws all the specification data from the OpenAPi Specification 2.0 specification document.

OAS is not only a specification. It also provides a full feature framework around it:

ActiveDocs is not a OAS replacement but an instantiation of it. With ActiveDocs, you don’t have to run your own OAS server or deal with the UI components of the interactive documentation. The interactive documentation is served and rendered from your 3scale Developer Portal.

The only thing you need to do is to build a Swagger-compliant specification of your API, add it on your Admin Portal, and the interactive documentation will be available. Your developers will be able to launch requests against your API through your Developer Portal.

If you already have a Swagger-compliant specification of your API, you can add it in your Developer Portal (see the tutorial on the ActiveDocs configuration).

3scale extended the OAS specification in several ways to accommodate certain features that were needed for our own interactive API documentation:

We recommend that you first read the original specification from the original source: the OAS Specification.

On the OAS site there are multiple examples of specifications. If you like to learn by example, you can follow the example of the Petstore API by the OAS API Team.

curl -X GET "http://example.com/api/pets?tags=TAGS&limit=LIMIT" -H "user_key: {user_key}"
curl -X POST "http://example.com/api/pets" -H "user_key: {user_key}" -d "{ "name": "NAME", "tag": "TAG", "id": ID }"
curl -X GET "http://example.com/api/pets/{id}" -H "user_key: {user_key}"
curl -X DELETE "http://example.com/api/pets/{id}" -H "user_key: {user_key}"

2.3.3. Useful tools

The JSON Editor Online is useful if you are very familiar with the JSON notation. It gives a pretty format to compact JSON, and it also provides a JSON object browser.

The OAS Editor is another useful tool. This enables you to create and edit your OAS API specification written in YAML in your browser and preview it in real time. You can also generate a valid JSON specification, which you can upload later in your 3scale Admin Portal. You can use the live demo version with limited functionality or deploy your own OAS Editor.

2.3.3.1. Extension to the OAS specification: auto-fill of API keys

Auto-fill of API keys is a useful extension to the OAS specification in 3scale ActiveDocs. In the parameters, you can define the x-data-threescale-name field with the following values depending on your API authentication mode:

• user_keys - returns the user keys for applications of the services that use API key authentication only.
• app_ids - returns the IDs for applications of the services that use App ID/App Key (OAuth and OpenID Connect are also supported for backwards compatibility).
• app_keys - returns the keys for applications of services that use App ID/App Key (OAuth and OpenID Connect are also supported for backwards compatibility).
• client_ids - returns the client IDs for applications of the services that use OAuth/OpenID Connect authentication only.
• client_sercrets - returns the client secrets for applications of the services that use OAuth/OpenID Connect authentication only.

API key authentication example

The following example shows using "x-data-threescale-name": "user_keys" for API key authentication only:

"parameters": [
  {
    "name": "user_key",
    "description": "Your access API Key",
    "type": "string",
    "in": "query",
    "x-data-threescale-name": "user_keys",
    "required": true
  },
]

App ID/App Key authentication example

For App ID/App Key authentication mode, specify "x-data-threescale-name": "app_ids" for the parameter that represents the application ID, and "x-data-threescale-name": "app_keys" for the parameter that represents the application key.

When you have declared your parameters, ActiveDocs will automatically prompt the ActiveDocs user to log in to the Developer Portal to get their keys as shown in the following screenshot:

If the user is already logged in, ActiveDocs will show the latest five keys that could be relevant for them so that they can test right away without having to copy and paste their keys.

Note

The x-data-threescale-name field is an extension to the OAS specification that will be ignored outside the domain of ActiveDocs.

Before you begin, you will need to have a Red Hat Single Sign-On instance set up, and OpenID Connect integration configured. See OpenID Connect integration documentation for information on how to set it up. Additionally, you will need to be familiar with how to set up ActiveDocs – see Add ActiveDocs and Create a (Swagger) spec.

This first example is for an API using the OAuth 2.0 client credentials flow. This API accepts any path and returns information about the request (path, request parameters, headers, etc.). The Echo API is only accessible using a valid access token. Users of the API are only able to call it once they have exchanged their credentials (client_id and client_secret) for an access token.

In order for users to be able to call the API from ActiveDocs, they will need to request an access token. Since this is just a call to an OAuth authorization server, you can create an ActiveDocs spec for the OAuth token endpoint. This will allow you to call this endpoint from within ActiveDocs. In this case, for a client credentials flow, the Swagger JSON spec looks like this:

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "OAuth for Echo API",
    "description": "OAuth2.0 Client Credentails Flow for authentication of our Echo API.",
    "contact": {
      "name": "API Support",
      "url": "http://www.swagger.io/support",
      "email": "support@swagger.io"
    }
  },
  "host": "red-hat-sso-instance.example.com",
  "basePath": "/auth/realms/realm-example/protocol/openid-connect",
  "schemes": [
    "http"
  ],
  "paths": {
    "/token": {
      "post": {
        "description": "This operation returns the access token for the API. You must call this before calling any other endpoints.",
        "operationId": "oauth",
        "parameters": [
          {
            "name": "client_id",
            "description": "Your client id",
            "type": "string",
            "in": "query",
            "required": true
          },
          {
            "name": "client_secret",
            "description": "Your client secret",
            "type": "string",
            "in": "query",
            "required": true
          },
          {
            "name": "grant_type",
            "description": "OAuth2 Grant Type",
            "type": "string",
            "default": "client_credentials",
            "required": true,
            "in": "query",
            "enum": [
                "client_credentials",
                "authorization_code",
                "refresh_token",
                "password"
            ]
          }
        ]
      }
    }
  }
}

For a resource owner OAuth flow, you’ll probably also want to add parameters for a username and password, as well as any other parameters that you require in order to issue an access token. For this client credentials flow example, you’re just sending the client_id and client_secret – which can be populated from the 3scale values for signed-in users – as well as the grant_type.

Then in the ActiveDocs spec for our Echo API we need to add the access_token parameter instead of the client_id and the client_secret.

{
  "swagger": "2.0",
  "info": {
    "version": "v1",
    "title": "Echo API",
    "description": "A simple API that accepts any path and returns information about the request",
    "contact": {
      "name": "API Support",
      "url": "http://www.swagger.io/support",
      "email": "support@swagger.io"
    }
  },
  "host": "echo-api.3scale.net",
  "basePath": "/v1/words",
  "schemes": [
    "http"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/{word}.json": {
      "get": {
        "description": "This operation returns information about the request (path, request parameters, headers, etc.),
        "operationId": "wordsGet",
        "summary": "Returns the path of a given word",
        "parameters": [
          {
            "name": "word",
            "description": "The word related to the path",
            "type": "string",
            "in": "path",
            "required": true
          },
          {
            "name": "access_token",
            "description": "Your access token",
            "type": "string",
            "in": "query",
            "required": true
          }
        ]
      }
    }
  }
}

You can then include your ActiveDocs in the Developer Portal as usual. In this case, since you want to specify the order in which they display to have the OAuth endpoint first, it looks like this:

{% active_docs version: "2.0" services: "oauth" %}





<script type="text/javascript">
  $(function () {
    window.swaggerUi.load(); // <-- loads first swagger-ui

    // do second swagger-ui

    var url = "/swagger/spec/echo-api.json";
    window.anotherSwaggerUi = new SwaggerUi({
      url: url,
      dom_id: "another-swagger-ui-container",
      supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
      onComplete: function(swaggerApi, swaggerUi) {
        $('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)});
      },
      onFailure: function(data) {
        log("Unable to Load Echo-API-SwaggerUI");
      },
      docExpansion: "list",
      transport: function(httpClient, obj) {
        log("[swagger-ui]>>> custom transport.");
        return ApiDocsProxy.execute(httpClient, obj);
      }
    });

    window.anotherSwaggerUi.load();

  });
</script>

This guide is designed to give you enough information to implement an API versioning system within 3scale.

Suppose you have an API for finding songs. Users can search for their favorite songs by different keywords: artist, songwriter, song title, album title, and so on. Assume you had an initial version (v1) of the API and now you have developed a new, improved version (v2).

The following sections describe the three most typical ways of implementing an APR versioning system using 3scale:

Complete the basics of connecting your API to 3scale before using this quick start guide.

If you have different endpoints for searching songs (by artist, by song title, and so on), with URL versioning you would include the API version as part of the URI, for example:

The 3scale Gateway would then extract the endpoint and the version from the URI. This approach allows you to set up application plans for any version/endpoint combination. You can then associate metrics with those plans and endpoints, and you can chart the usage for each endpoint on each version.

The following screen capture shows 3scale’s flexibility.

Figure 6.1. Versioning Plan Feature

The only thing left to do is go to [your_API_name] > Integration > Configuration in your 3scale Admin Portal and map your URIs to your metrics, as shown in the following diagram.

Figure 6.2. Mapping URIs to metrics

You now have two different versions of your API, each with different features enabled. You also have full control and visibility on their usage.

If you want to communicate to all of your users that they should move to the API v2, you can send an internal note asking them to do so. You can monitor who makes the move and see how the activity on v1 decreases while the activity on v2 increases. By adding the metric in your authorization calls to 3scale, you can see how much overall traffic is hitting v1 vs. v2 endpoints and get an idea of when it is safe to deprecate v1.

Figure 6.3. Versioning

If some users continue to use v1, you can filter out only those users to send another internal note about switching to v2.

3scale provides a three-step method for sending deprecation notices.

The following image provides a visual reference.

Figure 6.4. Sending deprecation note

For each authrep call that is made to an endpoint, you authenticate only once but report twice: once for the endpoint and once for the API version. There is no double-billing because the call can be authenticated only one time. For each call you make to any endpoint of a specific API version, you aggregate the hits on a convenient metric named after the version number (v1, v2, and so on), which you can use to compare full version traffic with each other.

You have the endpoint change for each version (api.cons.com/author_v1) with endpoint versioning. The gateway extracts the endpoint and the version from the endpoint itself. This method , as well as the previous method, allows the API provider to map external URLs to internal ones.

The endpoint versioning method can only be performed with the on-premise deployment method as it requires a URL rewrite using the LUA scripts that are provided as part of the on-premise configuration.

Almost everything (mapping, application plans features, and so on.) works exactly the same as in the previous method.

With custom header versioning, you use a header (that is, "x-api-version") instead of the URI to specify the version.

The gateway then extracts the endpoint from the path and the version from the header. Just as before, you can analyze and visualize any combination of path/version that you want. This approach has several inconveniences, regardless of the API management system you use. See API versioning methods, a brief reference for more information. Here are a few pointers on how 3scale works.

3scale supports the following authentication patterns out of the box:

3scale supports the authentication patterns detailed in the following sections.

API-key = 853a76f7c8d5f4a1ee8bf10a4e0d1f13

app_id = 80a4e03 app_key = a1ee8bf10a4e0d1f13853a76f7c8d5f4

3scale supports the Referrer Filtering feature that can be used to whitelist IP addresses or domain names from where an application can access the API. The API clients specify the referrer value in the Referer header. The purpose and the usage of the Referer header are described in the RFC 7231, section 5.5.2: Referer.

To enable the Referrer Filtering feature go to [your_API_name] > Integration > Settings, click the Require referrer filtering checkbox and click Update Service.

The developers with access to your API must configure allowed domain/IP referrers from the developer portal.

In the Admin Portal on the application details page for all applications that belong to this service a new Referrer Filters section displays. Here, the admin can also configure a whitelist of the allowed Referrer header values for this application.

You can set a maximum of five referrer values per application.

The value can only consist of Latin letters, numbers, and special characters *, ., and -. * can be used for wildcard values. If the value is set to *, any referrer value will be allowed, so the referrer check will be bypassed.

For the Referrer Filtering feature to work, the APIcast Referrer policy must be enabled in the service policy chain.

When the Require referrer filtering feature and the 3scale Referrer policy are enabled, the authorization works as follows:

The calls that are not authorized by AuthRep are rejected by APIcast with an "Authorization Failed" error. You can configure the exact status code and the error message on the service Integration page.

The API requests to the service using the OpenID Connect authentication mode should provide the access token in the JWT format, issued by the OpenID Provider, in the Authorization header using Bearer schema. The header should look like the following example:

Authorization: Bearer <JWK>

Example:

Authorization: Bearer: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2lkcC5leGFtcGxlLmNvbSIsInN1YiI6ImFiYzEyMyIsIm5iZiI6MTUzNzg5MjQ5NCwiZXhwIjoxNTM3ODk2MDk0LCJpYXQiOjE1Mzc4OTI0OTQsImp0aSI6ImlkMTIzNDU2IiwidHlwIjoiQmVhcmVyIn0.LM2PSmQ0k8mR7eDS_Z8iRdGta-Ea-pJRrf4C6bAiKz-Nzhxpm7fF7oV3BOipFmimwkQ_-mw3kN--oOc3vU1RE4FTCQGbzO1SAWHOZqG5ZUx5ugaASY-hUHIohy6PC7dQl0e2NlAeqqg4MuZtEwrpESJW-VnGdljrAS0HsXzd6nENM0Z_ofo4ZdTKvIKsk2KrdyVBOcjgVjYongtppR0cw30FwnpqfeCkuATeINN5OKHXOibRA24pQyIF1s81nnmxLnjnVbu24SFE34aMGRXYzs4icMI8sK65eKxbvwV3PIG3mM0C4ilZPO26doP0YrLfVwFcqEirmENUAcHXz7NuvA

The JWT token contains a signature that the token’s receiver can verify and ensure that the token was signed by a known issuer and that its content has not been changed. 3scale supports RSA signature based on the public/private key pair. Here, the issuer signs the JWT token using a private key. APIcast verifies this token using a public key.

APIcast uses OpenID Connect Discovery for getting the JSON Web Keys (JWK) that can be used for verifying the JWT signature.

On each request, APIcast does the following:

If any of the JWT validation or the authorization checks fail, APIcast returns an "Authenication failed" error. Otherwise, APIcast proxies the request to the API backend. The Authorization header remains in the request, so the API backend can also use the JWT token to check the user and client identity.

Using the Zync component, 3scale syncronizes the client (application) credentials between 3scale and the Red Hat Single Sign-On server configured through the OpenID Connect Issuer setting. Whenever a new application is created, updated, or deleted for a service configured to use OpenID Connect, Zync receives the corresponding event and communicates the change to the Red Hat Single Sign-On instance using RH-SSO API. The Section 8.3, “Configure Red Hat Single Sign-On integration” section provides the steps required to ensure that Zync has the correct credentials to use the RH-SSO API.

The API clients must get access tokens from the OpenID Connect issuer configured in 3scale, using any OAuth 2.0 flow that is supported by this OpenID provider. In case of Red Hat Signle Sign-On, the following flows are supported (the terms used in RH-SSO clients are specified in parenthesis):

When clients under OpenID Connect (OIDC) are created in 3scale, the corresponding clients created by Zync in Red Hat Single Sign-On (RH SSO) have only the Authorization Code flow enabled. This flow is recommended as the most secure and suitable for most cases. However, it is possible to enable other flows.

To test the integration, you must perform the steps listed in the following sections.

The service "API" in 3scale is configured to use the OpenID Connect authentication. The Public Base URL on the service "API" is configured to be https://api.example.com and the Private Base URL is configured to be https://internal-api.example.com.

The OpenID Connect Issuer field is set to https://zync:41dbb98b-e4e9-4a89-84a3-91d1d19c4207@idp.example.com/auth/realms/myrealm in the API integration and the client zync in the realm myrealm has the correct Service Account roles.

In 3scale, there is an application having the myclientid client ID, myclientsecret client secret, and a https://myapp.example.com Redirect URL. In Red Hat Single Sign-On, in the myrealm realm, there also exists a client having a myclientid client ID, myclientsecret secret, and https://myapp.example.com Valid Redirect URIs. Standard Flow is enabled on this client. There is a user configured in the myrealm realm having the myuser username and mypassword password.

The flow is as follows:

This documentation outlines the features of OpenAPI 2.0 specification (OAS) in 3scale 2.5 and provides steps to update an existing service or create a new one.

NAME
    openapi - Import API definition in OpenAPI specification

USAGE
    3scale import openapi [opts] -d <dst> <spec>

DESCRIPTION
    Using an API definition format like OpenAPI, import to your 3scale API

OPTIONS
       -d --destination=<value>                   3scale target instance.
                                                  Format: "http[s]://<authentication>@3scale_domain"

 -t --target_system_name=<value>            Target system name

OPTIONS FOR IMPORT
    -c --config-file=<value>                      3scale toolbox
                                                  configuration file
                                                  (default:
                                                  $HOME/.3scalerc.yaml)
    -h --help                                     show help for this command
    -k --insecure                                 Proceed and operate even
                                                  for server connections
                                                  otherwise considered
                                                  insecure
    -v --version                                  Prints the version of this
                                                  command

$ 3scale import openapi -d <destination> /path/to/your/spec/file.[json|yaml|yml]

$ 3scale import openapi -d <destination> http[s]://domain/resource/path.[json|yaml|yml]

$ tool_to_read_openapi_from_source | 3scale import openapi -d <destination> -