Register REST APIs in API Manager

Overview

API owners can use the API Manager web interface to register back-end REST APIs. You can manually create a new back-end API, or import a definition for an existing API (for example, in Swagger or WADL format). Using API Manager to register REST APIs means that you can register APIs in a browser, in multiple formats, without any service outage.

When a back-end API is registered, you can then virtualize it as a publicly exposed front-end API. Registered and virtualized APIs are governed by the API Gateway using configured policies. API administrators can use API Manager to manage registered APIs, and API consumers can use API Manager or API Portal to consume virtualized APIs in their applications.

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

Back-end and front-end APIs

In API Manager, the back-end API is the actual REST API that is routed to, and that is exposed by an application server on the network, or in the Cloud (for example, Twitter). You can use in API Manager to register a new back-end REST API manually, or to import a definition for an existing REST API in Swagger or WADL format. The following example shows a manually registered back-end API in API Manager:

Back-end API in the web console

In API Manager, the front-end API is the virtualized publicly exposed REST API that is hosted on the API Gateway, and which is invoked by client applications (for example, iPhone or Android apps). The following shows the example back-end API virtualized as a front-end API in API Manager:

Front-end API in the web console

By default, the front-end API is the same as the back-end API, proxying the API as is. However, you can edit the front-end API to present an enriched, public-facing API to client applications. For example, you can change the URL path, change and map parameters, or improve the documentation.

In addition, this separation of front-end API and back-end API definitions allows the back-end API to change over time. This means that you can control how changes are exposed to client applications, thus minimizing or eliminating the potential impact these applications. For more details, see Virtualize REST APIs in API Manager.

Enable an organization for API development

Before you can begin registering REST APIs for an organization in API Manager, you must first enable an organization for API registration and development. The API Manager welcome dialog prompts you to automatically create an API Development organization, which is enabled for API development by default.

If you do not create the default API Development organization, you must perform the following steps:

  1. Click the Client Registry > Organizations view in API Manager.
  2. Click the name of the organization to enable (for example, Acme Inc).
  3. In the API Development field, click On.

You can now register back-end APIs and virtualize front-end APIs for this organization.

Import an existing back-end REST API

To automatically register an existing back-end REST API in API Manager, perform the following steps:

  1. Click the API Registration > Backend API view in API Manager.
  2. Click New API > Import Swagger API or Import WADL API.
  3. In the Import API dialog, complete the following:
    • Source: Select the source type from the list (for example, Swagger or WADL definition file or URL).
    • File or URL: Click the browse button to select the definition file, or enter the URL.
    • API Name: A user-friendly name for the API (for example, Test API).
    • Organization: Select the organization from the list (for example, Acme Inc).
    • Authentication: For URL-based APIs only, enter a User name and Password if required.
  4. Click Import to import the API into the catalog.

When the REST API has been imported, it is displayed as read only in API Manager. The following example shows two imported APIs based on WADL and Swagger definitions:

Imported APIs in the web console

You can click an API name in the list to view its general details, methods, and schema model. The following example shows the details displayed for the petstore.json Swagger API:

Imported API details in the web console

Import an existing web service back-end API

To import an existing web service-based back-end API in API Manager, perform the following steps:

  1. Click the API Registration > Backend API view in API Manager.
  2. Click New API > Import WSDL API.
  3. In the Import Web Service dialog, complete the following:
    • URL: Enter the URL for the web service. For example:
    • http://wsf.cdyne.com/WeatherWS/Weather.asmx?WSDL
    • API Name: A user-friendly name for the API (for example, Weather API).
    • Organization: Select the organization from the list (for example, Acme Inc).
    • Authentication: For URL-based APIs only, enter a User name and Password if required.
  4. Click Import to import the API into the catalog.

Import an existing back-end API deployed on an API Gateway

To import an existing back-end REST or SOAP API that is already deployed on an API Gateway, perform the following steps:

  1. Click the API Registration > Backend API view in API Manager.
  2. Click New API > Import API from Topology.
  3. In the Import from Topology dialog, complete the following required settings:
    • Host: Enter the Admin Node Manager host name (for example, localhost).
    • Port: Enter the Admin Node Manager port number (for example, 8090).
    • Login Name: Enter your Admin Node Manager login name.
    • Password: Enter your Admin Node Manager password.
    • Group: Select the API Gateway group name (for example, AcmeGatewayGroup).
    • Instance: Select the API Gateway instance name (for example, AcmeGateway).
    • Service Type: Select REST API or SOAP service.
    • Service: Select the API Gateway service name (for example, AcmePayment.
    • API name: Enter the API name (for example, Acme Payment API.
    • Organization: Select the (for example Acme Inc).
  4. Click Import to import the API into the catalog.

Manually register a new back-end REST API

To manually register a new back-end REST API in API Manager, perform the following steps:

  1. Click the API Registration > Backend API view in API Manager.
  2. Click New API > New.
  3. In the API tab, complete the following general details:
    • API name: Enter a required name for the API (for example, Acme API).
    • Service type: Enter a service type for the API (for example, defaults to REST).
    • Organization: Select a required organization for the API (for example, Acme Inc). See also Enable an organization for API development.
    • Base path URL: Enter a resource path. Defaults to http://basepath.org.
    • Summary: Enter an optional summary for the API to display in the API Catalog.
    • Resource path: Enter a resource path for the API. Defaults to /api.
    • API version: Enter an optional version number for the API. Defaults to 1.0.
    • Description: Click the Edit tab, and enter an optional description for the API.

Create REST API methods

To add a REST API method to a newly registered API, perform the following steps:

  1. On the API Methods tab, complete the following details:
    • Method Name: Enter a required name for the API method (for example, GetProducts), and enter an optional Method summary.
    • Verb: Enter a required HTTP verb for the API method. Defaults to GET.
    • Path: Enter the path for the method. Defaults to /.
    • API version: Enter an optional response type for the API method (for example, a general type like int or string, or a custom type in the schema model for the API) Defaults to void.
    • Description: Click the Edit tab, and enter an optional description for the API.
  2. To add a parameter exposed by the API method, click the add button in the PARAMETERS section, and complete the following details:
    • NAME: Enter a required name for the parameter (for example, customer_name).
    • DESCRIPTION: Enter an optional description for the parameter.
    • TYPE: Select the parameter type (for example, query, path, form, body, or header). Defaults to query.
    • DATA TYPE: Select the parameter data type (for example, string, int, boolean, and so on). Defaults to string.
    • REQUIRED: Select whether the parameter is required. Defaults to No.
    • ALLOW MULTIPLE: Select whether multiple parameters are allowed. Defaults to No.
    To add more method parameters, click the add button in the PARAMETERS section.
  3. To specify content types that can be consumed by the API method, click the plus (+) button in the CONSUMES CONTENT-TYPE section, and enter the content type. For example, application/xml, text/plain, and so on. Defaults to application/json.
  4. To specify content types that can be produced by the API method, click the plus (+) button in the PRODUCES CONTENT-TYPE section, and enter the content type. For example, application/xml, text/plain, and so on. Defaults to application/json.
  5. To specify response codes that can be produced by the API method, click the plus (+) button in the RESPONSE CODES section, and select the response codes (for example, Create codes (201, 403, 500)).
  6. To add more API methods, click the add button on the top left.

Create the REST API model

Alternatively, for JSON-based APIs, you can directly enter the JSON schema model for the API on the Models tab. For more details, see http://json-schema.org/.

Manage back-end REST APIs

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:

Virtualize REST APIs in API Manager

When you have registered a back-end REST API, you can then virtualize it as a publicly exposed front-end API. For more details, see Virtualize REST APIs in API Manager.