Virtualize REST APIs in API Manager

Overview

When you have registered a back-end REST API, you can then virtualize it as a publicly exposed front-end API. The API Catalog stores information about the REST APIs that have been virtualized as front-end APIs. Virtualized REST APIs published in the API Catalog can be made available in API Manager for consumption by API consumers, and for administration by API administrators.

Note   You must first register a back-end REST API before you can virtualize a front-end REST API. For more details, see Register REST APIs in API Manager.

Virtualized REST API security

When you virtualize a REST API, you can configure it with security devices, which provide pre-built authentication and authorization mechanisms for the REST API. The following security devices are supported:

  • API Key
  • Amazon Web Services Signing - Authorization
  • Amazon Web Services Signing - Query String
  • HTTP Basic Authentication
  • Invoke Policy (custom authentication)
  • OAuth
  • OAuth (External)
  • Pass Through
  • Two-way SSL

This enables you to control the authentication and authorization mechanisms that are supported for the API. For example, an API with higher security requirements can be more restrictive in the authentication mechanism that it supports. You can also configure custom profiles to suit your requirements. You can also configure virtualized REST APIs and API methods with custom policies if required (for example, for request, routing, and response processing).

Virtualize a REST API as a front-end API

When you have first registered a back-end REST API in API Manager, you can then virtualize it as a publicly exposed front-end API. To virtualize a back-end REST API as a front-end API, perform the following steps:

  1. Click the API Registration > Frontend API view in API Manager.
  2. Click New API > New API from backend API.
  3. Select an existing backend API in the dialog (for example, petstore.json 1.1.0), and click Create. This displays the following page:

Imported API details in the web console

Import a previously exported API

Alternatively, you can virtualize an existing back-end API by importing a previously exported API (.json) file. For details on how to export a back-end API, see Manage back-end REST APIs. To import a previously exported API, perform the following steps:

  1. Click the API Registration > Frontend API view in API Manager.
  2. Click New API > Import API collection.
  3. In the Import API dialog, complete the following:
    • File: Click to browse to the previously exported API (.json).
    • Password: Enter the password if required.
    • Organization: Select the organization from the list (for example, API Development).
  4. Click Import.

Configure Inbound settings

When you have virtualized a REST API to create a front-end API, you can edit and configure the inbound request settings between the client and the API Gateway (for example, for customized authentication, authorization, or monitoring). To configure inbound settings, perform the following steps in API Manager:

  1. Select the Inbound tab.
  2. Edit the resource path in the text box under the API name. Defaults to /api.
  3. Select a required security device from the Inbound Security list. This enables you to configure pre-built inbound authentication and authorization mechanisms for the virtualized API. The most commonly used devices are API Key and Pass Through. The available options are as follows:
Security Device Settings
API Key Configure the following to enable API key authentication:
  • Name: Enter the required name for the device. Defaults to API Key Device.

  • API key field name: Enter a required name used to store the API key field in the inbound request. Defaults to KeyId.

  • API key location: Select the required location of the API key in the inbound request (Request Headers or Query string/form body). Defaults to Request Headers.

  • Remove credentials on success: Select whether to remove the user credentials from the message after successful authentication. This is selected by default.

AWS Signing (Authorization Header) Configure the following to enable access to the API using an Amazon Web Services authorization header:
  • Name: Enter a required name for the device. Defaults to AWS Signing Device (Authorization Header).

  • Remove credentials on success: Select whether to remove user credentials from the message after successful authentication. This is selected by default.

AWS Signing (Query String) Configure the following to enable access to the API using an Amazon Web Services query string:
  • Name: Enter a required name for the device. Defaults to AWS Signing Device (Query String).

  • API key field name: Enter a required name of the query-string parameter used to store the API key field in the inbound request. Defaults to AWSAccessKeyId.

HTTP Basic Configure the following to enable HTTP Basic authentication:
  • Name: Enter a required name for the device. Defaults to HTTP Basic Device.

  • Realm: Enter the realm required for HTTP basic authentication purposes (for example, Flickr). This enables clients to identify the zone that they are accessing. For example, the browser can then cache user credentials on a per-realm basis. The realm is required for all authentication schemes that issue an authentication challenge.

  • Remove credentials on success: Select whether to remove user credentials from the message after successful authentication. This is selected by default.

Note  When using HTTP basic authentication, the client application invoking the API must use the API key as username and the API secret as password, formatted as Base64Encode("APIKey:APISecret").
Invoke Policy

Configure the following to use a custom authentication policy:

  • Name: Enter the name of the custom security device. Defaults to Invoke Policy.
  • Policy to invoke: Select the authentication policy that this security device invokes. This lists policies already configured in Policy Studio in Server Settings > API Manager > Inbound Security Policies. For more details, see Configure API management settings in Policy Studio.
  • Use client registry: Select whether the authentication.subject.id identifier must match one of the application's external credentials in the Client Registry in API Manager. This is selected by default.
  • Traffic Monitor subject: If Use client registry is not selected, the API has no client information. Enter the subject name to display in the Traffic tab in API Gateway Manager. Defaults to ${authentication.subject.id}.
  • Description: Select where the Markdown description for this security device is located. For details on writing documentation with Markdown, see http://daringfireball.net/projects/markdown/. Select one of the following:

    • Use original policy description: Use the policy description specified when creating the policy in Policy Studio.
    • Use manual description: Get the description from the contents of a field. Enter the description in the Manual Description field.
    • Use markdown file location: Get the description from a file located on the server. Enter the path to this file in the Markdown file location field.

    Note   For security reasons, this file must start with an environmentalized variable and cannot attempt directory traversal. For example, the following path is valid:

    ${env.DOCUMENTS}/markdown/api.md

    The following paths are invalid:

    /opt/documents/api.md

    ${env.DOCUMENTS}/../markdown/api.md

    • Use external URL: Get the description from an external URL. Enter the URL in the External URL location field.

Note   Invoke Policy security devices generate an Authentication section in the API Catalog that displays the description entered when creating the security device.
OAuth

Configure the following to enable OAuth authorization:

General:

  • Access token store: Select a required OAuth access token store from the list. For details on how to add OAuth access token stores to this list, see Configure API Manager.
  • Scopes must match: Select whether the OAuth scopes match Any or All of the OAuth scopes configured in the next field. OAuth scopes are used to control how access tokens are accepted. For more details on OAuth scopes, see the API Gateway OAuth User Guide.
  • Scopes: Enter a comma-separated list of OAuth scopes used to manage how access tokens are accepted. Defaults to resource.WRITE, resource.READ.
  • Remove credentials on success: Select whether to remove user credentials from the message after successful authentication and authorization. Enabled by default.

Authorization:

  • Access token location: Select the required location of the OAuth access token in the inbound request (Request Header or Query string/form body). Defaults to Request Header.

  • Authorization header prefix: Select the header prefix used to authorize the request (Bearer or OAuth). Defaults to Bearer.

Grant Type: Implicit:

  • Enabled: Select whether to enable this simplified authorization code flow optimized for browser-based clients. Enabling advertises this grant type in the API Catalog. It is the role of the OAuth authorization server to support it. Disabling excludes this grant type from the API Catalog.

  • Login endpoint URL: Enter the authorization endpoint where resource owners can interact with the OAuth service to authorize access for the client application. This is the URL where client applications will redirect end users. Defaults to http://localhost:8089/api/oauth/authorize.

  • Login token name: Enter the response parameter name that will contain the access token. Defaults to access_token.

Grant Type: Authorization Code:

  • Enabled: Select whether the authorization code is obtained using an authorization server as an intermediary between the client and resource owner. Enabling advertises this grant type in the API Catalog. It is the role of the OAuth authorization server to support it. Disabling excludes this grant type from the API Catalog.

  • Request endpoint URL: Enter the authorization endpoint where resource owners can interact with the OAuth service to authorize access for client application. This is the URL where client application will redirect end users. Defaults to http://localhost:8089/api/oauth/authorize.

  • Request client ID name: Enter the name of the request parameter that will contain the client application ID. Defaults to client_id.

  • Request client secret name: Enter the name of the request parameter that will contain the client application secret. Defaults to client_secret.

  • Token URL: Enter the token endpoint URL where the client application will exchange an authorization code for an access token. Defaults to http://localhost:8089/api/oauth/token.

  • Token name: Enter the request parameter name that will contain the access code. Defaults to access_token.

OAuth (External)

Configure the following to enable OAuth authorization:

General:

  • Token information policy: Select a required OAuth token information policy from the list. This is a custom policy used to obtain and extract token information from the external OAuth provider. For details on how to add OAuth token information policies to the list, see Configure API Manager.

  • Scopes must match: Select whether the OAuth scopes match Any or All of the OAuth scopes configured in the next field. OAuth scopes are used to control how access tokens are accepted. For more details on OAuth scopes, see the API Gateway OAuth User Guide.

  • Scopes: Enter a comma-separated list of OAuth scopes used to manage how access tokens are accepted. Defaults to resource.WRITE, resource.READ.

  • Remove credentials on success: Select whether to remove user credentials from the message after successful authentication and authorization. Enabled by default.

  • Use client registry: Select whether to use the Client Registry in API Manager. If this is not selected, the API is effectively pass-through and the Client Registry does not apply API access or enforce quotas. If this is selected, API Manager can use OAuth external credentials to identify the client application, apply quotas, and assign a subject identifier for traffic monitoring. This is not selected by default because external OAuth providers typically use their own client registries.

  • Traffic monitor subject: Enter the identifier name used for clients from the external OAuth provider, which is displayed on the Traffic tab in the API Gateway Manager console. This value can be a selector. Defaults to ${oauth.token.client_id}.

  • Extract token attributes: Click the add button to specify OAuth token attributes to be extracted from the configured Token information policy and copied to the message whiteboard. For example, these can then be passed to request, response, or routing policies downstream. Specifying attributes ensures their values are retained on the whiteboard after invoking the policy. By default, the following attributes are extracted:

    • oauth.token.client_id

    • oauth.token.scopes

    • oauth.token.valid

Authorization: See the OAuth security device settings.

Grant Type: Implicit: See the OAuth security device settings.

Grant Type: Authorization Code: See the OAuth security device settings.

Pass Through Configure the following to enable pass-through authentication where the API Gateway passes the user credentials through to an authenticating server:
  • Name: Enter a required name for the device. Defaults to Pass Through Device.

  • Subject ID: Enter a required authentication subject ID. Defaults to Pass Through. This will be displayed in the Traffic view in the API Gateway Manager when the API is invoked using this device.

Two-way SSL To enable two-way (mutual) SSL authentication, the client must supply a certificate (signed by the server CA). By default, the client certificate must contain a Subject Common Name (CN) set to the API Key generated by API Manager. The CN value is evaluated at runtime using a selector, and used to look up the Key Property Store (KPS) to retrieve or validate the API key and application. You can configure the following settings:
  • Name: Enter a required name for the device. Defaults to Two-way SSL Device.

  • API key field: Enter the name of the selector used to look up the KPS to retrieve and/or validate the API key and application details. Defaults to ${certificate.subject.CN}.

  1. Click the Advanced button on the right to configure settings such as monitoring, sharing resources across domains, and per-API method overrides. The following shows an example:
  2. Frontend API: advanced inbound settings

Configure Advanced Inbound settings

When you click the Advanced button on the right, the following options are displayed in API Manager:

Advanced Setting Description
Monitor API usage Select whether to enable monitoring metrics for the REST API in the Monitoring > API Usage view.
Enable CORS from all domains Select whether to enable Cross Origin Resource Sharing (CORS) from all domains. For more details, see Configure CORS Profiles.
PER-METHOD OVERRIDE You can click to override the REST API level settings for specified REST API methods. Click the add button, select an API method from the list, and override the following settings as required:
  • INBOUND SECURITY PROFILE: Select a preconfigured security profile for the API method. For more details, see Configure Security Profiles.

  • CORS PROFILE: Select a pre-configured CORS profile for the API method. For more details, see Configure CORS Profiles.

  • MONITOR API: Select whether to monitor the REST API use for the API method.

  • MONITOR CLIENT: Select whether to monitor the client application use for the API method.

  • MONITOR API+CLIENT: Select whether to monitor which client applications are calling which REST APIs for the API method.

Configure Outbound settings

When you have virtualized a back-end REST API to create a front-end API, you can edit and configure the outbound request settings between the API Gateway and the back-end API. For example, this enables you to customize authentication, and request or response processing. The following page shows configuring an SSL authentication profile:

Front-end API outbound settings in the web console

To configure outbound settings, perform the following steps in API Manager:

  1. Select the Outbound tab.
  2. Select an optional profile from the Outbound authentication profile list. This enables you to configure a pre-built authentication mechanism for outbound communication between the API Gateway and the virtualized API:
Authentication profile Settings
No authentication No authentication is performed between the API Gateway and the back-end API.
HTTP Basic Configure the following to enable HTTP Basic authentication:
  • Name: Enter a required name for the profile. Defaults to HTTP Basic.

  • Username: Enter the required username (API key) used to access the API.

  • Password: Enter the optional password (API secret) used to access the API.

HTTP Digest Configure the following to enable HTTP Digest authentication:
  • Name: Enter a required name for the profile. Defaults to HTTP Digest.

  • Username: Enter the required username (API key) used to access the API.

  • Password: Enter the optional password (API secret) used to access the API.

API Key Configure the following to enable API key authentication:
  • Name: Enter a required name for the profile. Defaults to API key.

  • API key field name: Enter a required name used to store the API key field in the outbound request (for example, KeyId).

  • API key: Enter the API key required to access the API (for example, AIzaSyB6CzrBlkzuzDKJw0QaZhW9WwBV5IxXMS7).

  • Pass credentials as HTTP: Select the required location of the API key in the outbound request (Header, Query string, or Form).

SSL To enable SSL authentication, the API Gateway must supply a certificate signed by certificate authority used by the API. You can configure the following settings:
  • Name: Enter a required name for the profile. Defaults to SSL.

  • PFX/P12 Source: Select whether to specify the certificate using a .pfx or .p12 file, or using a URL.

  • PFX/P12 File or PFX/P12 URL: Browse to the PFX/P12 file, or enter the PFX/P12 URL.

  • PFX/P12 Password: Enter the password for the certificate.

  • Trust all certificates in chain: Select whether to trust all the CA certificates in the certificate chain. If this is not selected, only the top-level CA is trusted. This setting is selected by default.

  1. Click the Advanced button on the right to configure settings such as request or response processing, routing, and per-API method overrides. The following shows an example:
  2. Frontend API: advanced outbound settings

Configure Advanced Outbound settings

When you click the Advanced button on the right, the following options are displayed in API Manager:

Advanced Setting Description
Request policy Select an optional request processing policy for the API. For example, you could use this pre-configured policy to check the request message for additional authentication, authorization, or validation. No request policies are configured by default. For details on how to make custom request policies available in the list, see Configure API Manager.
Response policy Select an optional response processing policy for the API. For example, you could use this pre-configured policy to validate or transform outbound response messages. No response policies are configured by default. For details on how to make custom response policies available in the list, see Configure API Manager.
Default method routing Select an optional routing policy for virtualized API method calls. For example, you could use this pre-configured policy to route to a backend JMS service. API method calls are routed to the API proxy in API Manager by default. For details on how to make custom routing policies available in the list, see Configure API Manager.
PER-METHOD OVERRIDE You can click to override the REST API level settings for specified REST API methods. Click the add button, select an API method from the list, and override the following settings as required:
  • REQUEST POLICY: Select an optional request processing policy for the API method (for more details, see Configure API Manager).

  • RESPONSE POLICY: Select an optional response processing policy for the API method (for more details, see Configure API Manager).

  • DEFAULT METHOD ROUTING: Select an optional routing policy for the API method (for more details, see Configure API Manager).

  • EDIT API PROXY: Click Edit to add parameters to the API method. To add parameters, click the add button, and configure the following settings:

    • OUTBOUND PARAMETER: Enter the parameter name (for example, customer_name).

    • PARAMETER TYPE: Enter the parameter type (for example, query, path, form, or header).

    • DATA TYPE: Enter the parameter name (for example, string, int, and so on).

    • REQUIRED: Select whether the parameter is required.

    • OUTBOUND VALUE: Enter the parameter value (for example, john doe or ${params.path.id}).

    • EXCLUDE: Select whether to exclude the parameter.

    • DEFAULT MAPPING: Select whether the parameter is mapped by default.

  • AUTHENTICATION PROFILE: Select an optional authentication profile for the API method.

Configure API information

The API tab enables you to view and edit the API information to be displayed in the API Catalog. For example, this includes general settings such as the API name, version, graphic, documentation, and tags.

Configure general API information

You can configure the following settings in the GENERAL section:

  • Image: Click the Add Image box, and browse to the location of the graphic file for your API.
  • API Name: Enter a value to edit your API name.
  • API Version: Enter a value to edit your API version.

Other details such as the API state, owner, date are read-only.

Configure API documentation

You can configure the following in DOCUMENTATION > Description:

  • Use original description: Uses the description specified when the back-end API was registered.
  • Use manual description: Click the Edit tab, and enter a description.
  • Use markdown file location: Enter the location in Markdown file location (for example, ${environment.VINSTDIR}/../markdown/API/API.md).
  • Use external URL: Enter the location in External URL location (for example, https://api.any.org/doc#myapi).

Configure API tags

The TAGS section enables you to add tags to categorize and help find your API in the API Catalog. Click the add button, and enter a tag name (for example, Department) and values (for example, Engineering,Testing). You can add multiple tags for your API.

Tip   You can enter multiple tag values in a comma-separated list without any spaces between each value.

Configure API method information

You can use the Method tab to configure the API method information to be displayed in the API Catalog. For example, this includes testing the method, configuring its documentation, and adding tags. For example, click Try method to invoke the method for test purposes. Authentication credentials are automatically formatted and passed in the test request. Other settings such as method parameters and content types are displayed as read-only.

For details on configuring API method documentation and tags, see Configure API information.

Configure Security Profiles

You can use the Security Profiles tab to create custom security profiles with multiple security devices, which can then be applied as per-method override in the Inbound settings for the front-end API.

To create a security profile, perform the following steps:

  1. Click the add button on the left.
  2. In GENERAL, enter a Name for the security profile.
  3. In DEVICES, click the add button, select a security device from the list, and configure its settings. For details on configuring each security device type, see Configure Inbound settings.
  4. Repeat to add multiple security devices if required.
  5. You can click Up or Down to change the order in which security devices are invoked, or Edit to change any settings as required.
Note   Multiple security devices are combined using an OR logic. This means that if authentication to the first security device fails, authentication to the second security device is attempted, and so on.

Configure Authentication Profiles

You can use the Authentication Profiles tab to create custom authentication profiles, which can then be applied to the front-end API in the Outbound settings.

To create an authentication profile, click the add button on the left, select an authentication profile from the list, and configure its settings. For details on configuring each authentication profile type, see Configure Advanced Outbound settings.

Configure CORS Profiles

You can use the CORS Profiles tab to create profiles for Cross Origin Resource Sharing, which can then be applied to the front-end API in the Outbound settings. To create an authentication profile, click the add button on the left, and configure the following settings:

  • GENERAL: Enter a descriptive Name for the profile.
  • ORIGINS: Click the add button, and enter the list of domains allowed to access this API (for example, http://test.mydomain.org, or a wild-carded value such as http://*.mydomain.org). Defaults to * to allow all domains.
  • ALLOWED HEADERS: Click the add button, and enter the list of HTTP headers that can be used when invoking this API. This list of headers is defined by the value of the Access-Control-Request-Headers CORS header.
  • EXPOSED HEADERS: Click the add button, and enter the list of HTTP headers to be exposed to the client in response to an invocation of this API.
Note   This does not include simple headers such as Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, and Pragma.
  • CREDENTIALS SUPPORT: Select whether the API advertises that it supports user credentials. When selected, the Access-Control-Allow-Credentials CORS header is sent in the response, with a value of true. This setting is not selected by default.
  • PREFLIGHT RESULT CACHE: Enter how long the results of a CORS preflight OPTIONS request can be stored in the client preflight result cache. When configured, the Access-Control-Max-Age CORS header is sent in the response.

For more details on using CORS, see the API Gateway Policy Developer Guide. This provides more background information and explains how to configure CORS for specific HTTP services and relative paths in Policy Studio. For example, this may be useful when using a third-party load balancer, and you need to configure a CORS profile for the default API Portal HTTP service in Policy Studio.

Configure CA Certificates

You can use the CA Certificates tab to add Certificate Authority (CA) certificates, which can be used for the Outbound SSL settings. To add a new CA certificate, perform the following steps:

  1. Click the add button on the left, and configure the following:
    • Source: Select the source of the CA certificate (PKCS12, PEM, DER file or URL).
    • File or URL: Browse to the CA source file, or enter the URL, and optional user name and password if required.
  2. Click Import.

Manage the front-end REST API lifecycle

When you have registered the back-end REST API, you can select it in the list of registered APIs, click Manage selected, and chose one of the following options:

  • Delete: Deletes the selected REST API(s) from the API Registration > Frontend API view. You can delete APIs registered as back-end REST APIs in the Backend API view.
  • Publish: Publishes the selected REST API to be consumed by API consumers. You can edit the API Name, and enter an optional Virtual host name. When published, the API can be assigned to any organization or application. The API is locked, and no further edits are allowed.
  • Unpublish: Unpblishes the selected REST API. When unpublished, the API is only available to the API administrator and API owners. The API can be edited, published, or deleted.
  • Deprecate: Select whether to Retire API at specific date, and enter a Retirement date. When selected, the published API is displayed with a date when it will be retired (unpublished) from the API Catalog, and is no longer available to client applications. When deprecated, the API is still published and clients can continue to discover and use the API. Only a published API can be deprecated and unpublished.
  • Undeprecate: Undeprecates the selected deprecated REST API.
  • Upgrade: Upgrades the selected API to a more recent version if one exists.
  • Grant Access: Grants access to the selected APIs. You can select whether to Grant API access to all organizations, specific organizations, or organizations with access to specific APIs.
  • Export API: Exports a copy of the selected REST API in (.json format), which can then be imported into API Manager as required. You can select whether to encrypt and add a password.
Contents
Comments