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 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.

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:

  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.

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 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) registered in the API Registration > Backend API view. You can delete APIs created as front-end REST 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. You can clone REST-based APIs only.
  • Export API: Exports a copy of the selected back-end REST API (in .json format). You can then import this into another API Manager environment as required as a back-end REST API.
  • Download original API description: For APIs imported from Swagger or WADL definitions, downloads a copy of the original 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