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 owners and 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 and select one of the following:
    • Import Swagger API: Import an API in Swagger format. Only JSON format is supported for Swagger API definition files. For more details on Swagger, see http://swagger.
    • Import RAML API: Import an API in RESTful API Modeling Language (RAML) format. Importing RAML files that include references to external files is not supported. For more details on RAML, see http://raml.org/.
    • Import WADL API: Import an API in Web Application Description Language (WADL) format. For more details on WADL, see https://wadl.java.net/.
  1. In the Import API dialog, complete the following:
    • Source: Select the source type from the list (for example, Swagger, RAML, 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.

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 Swagger API:

Imported API details in the web console

Note   It is not recommended to have spaces or the URL encoded %20 in the base path URL.

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.

Limitations of web services support

API Manager does not support the following features:

  • WSDL import from file: You can only import a web service from a URL in API Manager, and must use Policy Studio to import from a file.
  • WS-Policy/WS-Security: If this is required, you must register the web service using Policy Studio.
  • Schema validation: If schemas are available, you can validate using custom request/response policies (see API Manager custom policies). Otherwise, you should register using Policy Studio.
  • Binding/operation selection: You cannot select specific bindings/operations for import. If this is required, you must use Policy Studio.
  • Cloning: You cannot clone an API registered from a web service.
Tip   When your web service schemas are loaded in API Manager, they are protected by your chosen front-end API security device. Your client testing tool may be able to reach the WSDL, but not the schema imports without the appropriate key/credentials.

For details on registering web services using Policy Studio, see Manage web services in the API Gateway Policy Developer Guide.

Import an existing Cloud-based back-end API

Note   Before importing a Cloud API, you must first ensure that the API connector and OAuth profile for the Cloud API have been configured. For example, see Configure OAuth client credentials for Salesforce.com.

To import a Cloud-based back-end API for existing Cloud-based APIs in API Manager, perform the following steps:

  1. Select API Registration > Backend API.
  2. Click New API, and select Import from Salesforce.com or Import from ServiceNow
  3. Enter your login credentials from your Cloud API provider (for example, Salesforce.com) in the dialog (if prompted).
  4. Select the Cloud APIs that you require in the dialog.
  5. Click Import to import the selected APIs as a single back-end API in API Manager.

For a detailed example, see Cloud application connectors.

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 when logged in as API administrator:

  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 organization (for example Acme Inc).
  4. Click Import to import the API into the catalog.
Note   The Import from Topology feature is only available API administrators.

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 data model

For JSON-based REST APIs only, you can enter the JSON schema model for the API data on the Models tab. This tab is not displayed for web service APIs.

This model is optional and describes the data that is passed to the API as the request payload or returned from the API as the response payload. The data model is then displayed for application developers in the API Catalog in API Manager or in API Portal.

Tip   You can add/edit the data model for a manually created REST API, but this is read-only for an imported REST API. In this case, the data model is part of the imported definition, and cannot be changed. However, if you need to update the model (for example, to fix a bug in the schema), you can do this by cloning the API as described in the next section.

For more details on the API Catalog, see Consume APIs in API Manager. For more details on JSON schema models, see http://json-schema.org/.

Manage back-end API lifecycle

When you have registered the back-end 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 API(s) registered in the API Registration > Backend API view. You can delete APIs created as front-end APIs in the Frontend API view.
  • Clone API: Creates a copy of the selected REST API, which you can then edit as required.
Note   You cannot clone a back-end API imported from a WSDL-based web service.
  • Export API: Exports a copy of the selected back-end API (in .json format). You can then import this into another API Manager environment as required as a back-end API.
  • Download original API description: For APIs imported from Swagger or WADL definitions, downloads a copy of the original REST API definition.

Next steps

When you have registered a back-end REST API, the next step is to virtualize it as a publicly exposed front-end API. For more details, see Virtualize REST APIs in API Manager.

Related Links