API Manager Publisher

Overview

As a publisher, you can create and publish an API for consumption by any service or application. Subscribers can consume the APIs and use the APIs in their applications. Using the portal, you can design APIs and manage the APIs throughout their lifecycle interactively. You can collaborate with consumers, engage developers, and gather important information and insights necessary to get your API up and running.

When you log in to the API Manager portal as a publisher, you can see the following options:

Switching between roles

When the API Manager administrator assigns more than one role (for example, publisher and subscriber) to you, you can switch between the roles and log in as publisher or subscriber.

Creating a REST API

Follow these steps to create a REST API in API Manager.

Click Create REST API. The Basic Settings page displays.

Enter the following details in the Basic Settings section.

Field	Description
API Name	Name of the new API. Once you create an API, you cannot change its name.
Context	Defines a context for a service request. Resources are viewed hierarchically via their URI names, offering consumers a friendly, easily understood hierarchy of resources to leverage in their applications.
Description	The description of the API.
Visibility	Visibility settings prevent certain roles from viewing and modifying APIs from another user. Select Public, Intranet, or Partner modes of publishing an API. In Public mode, all levels of users can see an API.
Version	The version of the API. An API can have multiple versions. The version must always begin with v or V followed by a whole number or decimal. The version can also begin without v or V. For example,
Make Default	Select this check-box if you want your API version to be the default. If you have multiple versions of the same API, you can choose the one to be the default.
Lifecycle	Stages of progression of an API. Select from Draft, Published, Deprecated, or Retired.

Define the API endpoints. An endpoint defines the address to a web service. You can expose both REST and SOAP services to consumers through APIs. Enter the following details in the Endpoints section.

To choose the type of endpoint- HTTP URL or Load Balancer, click Endpoints.

If you select Load Balancer, choose the load balancing algorithm.

There are two load balancing algorithms that the API Manager uses:

Round robin: In this method, the load is balanced sequentially across the API endpoints. All the endpoints are assigned similar load. The endpoints also similar performance. Click Add Another Endpoint to add the endpoint URLs for load distribution.

Weighted Round Robin: In this method, the load is balanced across the endpoints according to a “weightage” factor that you can assign to each endpoint. The load is divided in terms of the weights assigned. If the weights assigned to the three endpoints are 100, 50, and 50 respectively, the first endpoint handles twice as many requests as the second third endpoints. In the following example:
- The first endpoint handles the first two requests.
- The second endpoint handles the third request.
- The third endpoint handles the fourth request.

To enable caching of your newly created REST API, click Caching. The benefits of caching an API are speed and reduced load on server. Select the Enable Caching check-box and enter the caching timeout in seconds.

To enable caching at resource level, select the Apply to all resources check-box. Caching at resource level prevents a separate back-end call to check the authorization type and throttling level of a resource, every time a request to the API comes.

To enable Cross-Origin Resource Sharing (CORS) of the API, click CORS. CORS allows restricted resources in the API to be accessed from another domain. CORS is a standard mechanism that allows JavaScript calls executed in a web page to interact with resources originating from an external domain. All known browsers enforce this policy.

To know more about CORS, refer to CORS.

Adding resources to the API

In the Resources section, you can separate your API into resources. You can access or manipulate these resources using HTTP requests where each method, GET, PUT, or POST, and so forth, performs to its specifications.

A resource is typically defined as an object with a type and the methods that operate on it.

Resources can be grouped into collections. There are also singleton resources that exist outside a collection.

To add a resource to the new API:

Enter the name of the resource in the Endpoint Path field. For example, if your endpoint URL represents an online store, you can define the following resources:

/products. For example, http://endpointurl/products
/orders. For example, http://endpointurl/orders
Nested orders, {orderId}/status. For example, http://endpointurl/{orderId}/status

Enter a description of the API in the Nickname field. A nickname is a one word description of the API. The resource uses the nickname as an identifier. For example, the nickname /checkPhone can be assigned to the resource /CheckPhoneNumber.

Select an HTTP method in the URL to make a request.

To add the new resource, click Add Resource. The resource with an HTTP method displays along with the mapped name (the name given to the resource).

Click the HTTP method to change the return type, authentication type, rate limits, and scope of the API.

You can also change the scope of the API resources.

Add the query parameters to the API path and modify the properties.

To define the output format or response, click Manage Models. You can add or modify a response format and create a return type for a resource.

Trying out an API

After creating an API, you can test the API to see the response and other details. Click Test this API on the left pane.

Enter the value of the parameter and select the output format. Click Run API Call. You can see the response details, as shown below:

Viewing all APIs

In this page, you can view all APIs you have:

Published
Created as draft
Deprecated
Retired

Also, you can filter the list of APIs according to API visibilit. For example:

Public
Partner
Intranet

API Catalog

In this page, you can filter all APIs according to the visibility and time (newest or oldest).

Changing the header logo and title

You can change the logo and title on the header area of the administrator portal.

Navigate to the <API Manager Installation Directory>/wwwroot/portal/conf folder and open the fileconfig.json. Modify the following properties:

{

"headerTitle": "API Manager Portal",

"adminHeaderTitle": "API Manager Administrator",

"headerLogoPath": "images/CF-Logo.png"

}

Cross-Origin Resource Sharing (CORS)

CORS allows restricted resources in the API to be accessed from another domain. CORS is a standard mechanism that allows JavaScript calls executed in a web page to interact with resources originating from an external domain. All known browsers enforce this policy.

Allowed HTTP Methods - A list of HTTP methods that are allowed, for example, GET, PUT, POST, and so forth.

Allowed Origins - Represents the origin of a request or *. For a request to be allowed cross-domain, add the header specified in Allowed Origins to the request. For example, if the server responds with allowed origin as http://examplerest.com, then only requests from http://examplerest.com are allowed.

Note: The Access-Control-Allow Origin Header should contain the list of origins that can use this API from the browser. The header also allows a wildcard value * adding it would allow any website can invoke this API and retrieve the response. The wild card value can be abused in some cases like where an external website part of internet can be able to consume the API which is part of Intranet zone.

Allowed HTTP Headers - A list of allowable custom request headers, for example, Origin, Content-Type, and so forth.

Allowed Expose Headers - Specify the headers you want to grant explicit permissions so that the client can read those headers. Doing so ensures that the client triggers a cross-origin request.

Preflight Max Age - Specify the amount of time (in seconds) for the browser to cache the response to a request.

Example

For example, you want to GET data from http://api.examplerest.com/user from http://examplerest.com. There is an access token, xyz123, that you can pass in the Authorization header to authenticate the request.

The browser sends an OPTIONS request to the server with the following header:

OPTIONS /user

Origin: http://www.examplerest.com

Access-Control-Request-Method: GET

Access-Control-Request-Headers: Authorization

Since you want to allow the request, you respond to the request with the header:

Allowed-Origin: http://www.examplerest.com

Allowed HTTP Headers: AUTHORIZATION

Allowed HTTP Methods: GET

The browser now sends the GET request to your server where the API is hosted.

Caching

To enable caching of your newly created REST API, click Caching. The benefits of caching an API are speed and reduced load on server. Select the Enable Caching check-box and enter the caching timeout in seconds.

Converting SOAP endpoints to REST endpoints

To convert a ColdFusion SOAP service into a REST service, click Create REST API from SOAP.

In the General Information section, enter the new API information, such as:

API Name
Context
Visibility
Version
Description
WSDL URL

In the WSDL URL field, enter a SOAP CFC URL.

The example WSDL URL has a single port type. A WSDL <portType> element defines a web service, the operations that can be performed, and the messages that are involved.

This WSDL has a single binding. WSDL bindings define the message format and protocol details for a web service. In this case, axis1.cfcSoapBinding is the binding.

The soap:binding element has two attributes - style and transport. The style attribute can be either rpc or document.

The transport attribute provides a namespace for a SOAP transportation protocol.

For example, transport="http://schemas.xmlsoap.org/soap/http" represents SOAP over HTTP.

Click Fetch. You can see the WSDL resources mapped to REST resources. Choose the port type.

On the WSDL Mapping Wizard, you can view the list of all the operations of the Axis1 port type.

Expand a method from the list. The REST path of the method displays along with the MIME-type and the method type (GET, PUT, POST, and so forth).

For operations with method type POST or PUT, select the type of parameter for an argument associated with the operation.

PATHPARAM describes a path parameter in the URL. For example, in the method GET /directory/{directoryName}, {directoryName} is the PATHPARAM.
QUERYPARAM describes a parameter of the query string. For example, /search?q=johndoe.
FORMPARAM inserts web form parameters into a REST service.

To generate the REST resources, click Generate REST Endpoints. Once you publish, you cannot change the name of the API.

The REST endpoint displays after the conversion. The new URL is:

You can use the URL in the following ways:

To view the swagger resource listing document, enter the following in the address bar of a browser:

You can see the following:

To view the root resource path document, enter the following in the address bar:

You can see the following:

In the SLA Plans section, select a plan or plans for the API.

In the Resources section, there is also a list of all SOAP operations that are converted to REST. You can see the methods with each operation.

Click Publish to make the REST API available to subscribers.

Importing REST API from ColdFusion

Before you import a REST API from ColdFusion server, set up the server. For more information, see CF Discovery setup.

Set up a CF service that returns the date. In the cfc, use the method GET and a REST path, for example, /GetCurrentDate. Create a folder in the web root of your ColdFusion server and save the cfc.

On the Create API screen, click Import REST API from ColdFusion.

View the list of CF services and click Import for the service you want to import from CF server.

Once you generate the resources defined in the cfc, set up the SLA plans and the authentication method for the API. To publish the API, click Publish.

Importing REST API from Swagger

Swagger is a specification and a framework to build API documentation and sandboxes, and to generate the code of an API client.

In ColdFusion API Manager, you can import REST resources based on Swagger specifications and publish them.

On the Create API screen, click Import REST API from Swagger.

Enter a Swagger API. In this example, use a Petstore server. Click Import.

Enter the API information and set the visibility.

Set the authentication type for the API.

To view existing Petstore resources or add a resource, click Resources on the left pane on the screen.

To publish the API, click Publish.

Importing a SOAP API

You can pass a SOAP API through proxy in API Manager. You can:

Apply security authentication to SOAP web services
Apply rate limiting
Apply throttling
Collect metrics and logging information

As a publisher, you enter the WSDL URL to a proxy WSDL URL, where the subscriber gets the modified URL with proxy SOAP endpoints and location of the XSD.

An example of proxy WSDL is http://service.adobe.com/<API name>/<version>/?wsdl

If you host a SOAP proxy behind a web server or a particular IP, modify the domain URL through the Administrator portal. The SOAP endpoint is on the domain that the administrator defines in the Domain URL field.

The subscriber sends request via proxy endpoint and the request is mapped to the actual endpoint.

In the API Manager, click Import SOAP API.

Enter the details on the screen. Set the API visibility to Public. Enter a WSDL URL in the WSDL URL field. For example, enter the WSDL URL http://www.thomas-bayer.com/axis2/services/BLZService?wsdl.

This WSDL generates request and response for a web service using which you can fetch Bank Sort Codes (called Bank BLZ codes) for banks in Germany.

Click Fetch. You can see both the actual and proxy WSDLs. You can also see the WSDL ports along with their bindings, and actual and proxy SOAP endpoints. For example,

Choose the type of authentication for the API from the Type drop-down list.

Choose an SLA plan or create a plan. To make the plan subject to approval, select the Approval check-box.

When you make an SLA plan ssubject to approval, an API subscriber cannot use the API unless you grant the subscriber approval to use the API under that SLA plan. For example, if you grant a subscriber GOLD plan subject to approval, the subscriber can only subscribe to GOLD if you approve the subscription request.

For more information, see Approving subscriptions.

To publish the API and make it available to subscribers, click Publish.

Once you publish the API, a subscriber can try out the API and use the API in different applications.

To see how a subscriber can try out the API, see Try-out SOAP API.

Authenticating an API

In the API Manager, you can use API keys to authenticate your APIs and applications. The API Manager generates the API keys and enable you to add API key-based authentication to your APIs.

Validation using API keys is a type of security you can enforce while creating an API. Applications use the API key and the API Manager checks to see if the API key is in an approved state for a resource.

The API Manager uses three API authentication types:

apiKey
basicAuth
OAuth2

Authentication types

apiKey

An API Key is an opaque token, which is a simple form of authentication to consume an API. To acquire an API Key, create an application as a subscriber.

Consuming an API protected using API Key

In a request, you can pass an API Key to the API Manager in a request in one of the following ways:

Header: The api_key header can be used to pass the API Key to the API runtime.
Query Parameter: The api_key query parameter can be used to pass the API Key.
Form Parameter: The api_key form parameter can be used to pass the API Key.

To know more about authentication using API Key, see API Key.

basicauth

Basic authentication is the simplest form of authenticating a user by passing the username and password in the request to consume an API. The API Manager allows protecting an API using the Basic authentication scheme.

A publisher can configure the user store to be used for the authentication. Also, if the API resource is protected with a scope configured with roles, then the API Manager also authorizes the role during the consumption of the API call.

In basic authentication, you can enforce authentication according to user stores.

From the User Store drop-down list, select a user store. The API administrator creates a user store.
Create a scope. A scope defines a role defined in a user store. Enter the name of the scope and select a role.
To add the newly created scope, click Add Scope.

To know more about basicauth authentication, see Basic authentication.

OAuth2

OAuth2 is a standard for delegating authorization to an application on behalf of the user without providing the password. Instead of the user password, an access token having limited lifetime with the limited access (using scopes) will be provided to the application. Depending on the type of application, obtaining an access token varies and are called grant types.

In the API Manager,

The application requests authorization to access resources in an API you create.
If you approve the request, the application receives an authorization.
The application requests an access token after it presents authentication of its identity.
The API issues an access token to the application.

To set up OAuth2,

Select an Oauth type, USERSTORE or SAML. If you select USERSTORE, select a user store defined in LDAP or database connection.
Add a scope.

The subscriber creates an application. After you approve the request, the subscriber uses the client secret key to make the API requests.

To know more about OAuth2 authentication, see OAuth2 authentication.

Adding tiers to an API

You can enforce limits on each resource consumption and assign multiple consumption levels. You can change the API-throttling level of a plan and add new plans. Throttling in API Manager imposes limits on the maximum rate at which the API Manager can make requests.

The administrator configures an API Service Level Agreement (SLA) by selecting one of the two algorithms. The administrator then adds an SLA by specifying its rate and throttle limits.

As a publisher, you can create a subscription plan and assign throttling limits to an API. To modify an existing tier:

Select any plan created by the administrator.

Click the name of the plan and change its properties.

Modify the API rate limit. You can only limit an API request rate to number of requests per second, minute, or hour.

Modify the API throttle limit. You can only limit an API throttle rate to number of requests per day, week, or month.

Select the type of limit for the API requests.

There are two options:

Hard: If you select this option, the number of API requests cannot exceed the throttle limit.
Soft: If you select this option, you can set the API request limit exceed a percentage. For example, if you set the Exceed Limit to 90%, the number of API requests can exceed 90% of the prescribed limit.

To approve an API request plan, select the Approval check-box.

To add the new SLA plan, click Add Plan.

Adding rate limits to API resources

You can add rate limits to the resources of the API for the SLA plans which the API subscribe. Once the API exceeds the rate limit, the subscriber sees Status 429 in the response header. There is also a try-out rate limit for the subscriber. You do not have any limit to try out your APIs.

To add rate limits to the API resources:

Enter the number of requests for an SLA plan.

Save the information. The API resources get new rate limits.

Specifying endpoints

An endpoint defines the address to a web service. You can expose both REST and SOAP services to consumers through APIs. Enter the following details in the Endpoints section.

Choose the type of enpdpoint.

HTTP URL: If you choose this option, enter a primary URL or URLs that contains the resources. You can also enter a test endpoint URL to test your APIs in a sandboxed environment.

Load Balancer: If you choose Load Balancer, choose the load balancing algorithm. There are two load balancing algorithms:

Round Robin: In this method, the load is balanced sequentially across the API endpoints. All the endpoints are assigned similar load and have similar performance. Click Add Another Endpoint to add the endpoint URLs for load distribution.
Weighted Round Robin: In this method, the load is balanced across the endpoints according to a "weightage" factor that you can assign to each endpoint. The load is divided in terms of the weights assigned. If the weights assigned to the three endpoints are 100, 50, and 50 respectively, the first endpoint handles twice as many requests as the second and third endpoints.

Adding the API business details

Enter the details of your business in the Business Info section.

Approving subscriptions to an API

You can approve or reject subsccriptions to an API. Click Subscriptions and view the list all subscription requests.

Deleting a subscriber

You can delete a subscribed user in the Subscribed Users page. Click the trash button under Actions to delete a subscriber.

Viewing subscribed users

View a list of all subscribed users. You can see the following for each user:

User name
First and last name
Email id
Phone
Action

Viewing notifications

On the Publisher portal, you can check for notifications for scenarios, such as:

Request to approve API subscription
Approved API subscription
Termination or deprecation of an API
Errors in API endpoints
An SLA reaches its limits

When a subscriber subscribes to an application, you get a corresponding notification.

When you click Notifications, you can view all subscriber messages and take appropriate action.

Publishing the API

Click Publish to publish the API.

Viewing the analytics dashboard

The analytics dashboard for a Publisher consists visualizations for API metrics, successful and failed requests, number of API requests, and so on. Click Analytics to launch the Publisher analytics page.

There are five types of dashboards in the Publisher portal:

Home
APIs
APIs and Versions
Developers
Errors

Home: On the Home dashboard panel, you can see the following visualizations:

1	The number of API requests within a time range with total requests and erroneous requests.
2	A donut-chart representation of API success and errors.
3	The metrics data like average response time, number of API requests for APIs, and so forth.
4	The average response time of an API in milliseconds.
5	Cache hit or miss.
6	Line chart of successful and unsuccessful API requests.

APIs: On the APIs dashboard panel, you can see the following visualizations:

1	The number of requests for the top five APIs and the versions.
2	Donut-chart for the number of API requests by the top five applications.
3	Donut-chart for the percentage of successful and unsuccessful API requests with comparison of the versions of an API.
4	Bar-chart for the average response time for an API.
5	Line-chart for the number of requests by the top three APIs.
6	The number of API requests.
7	Donut-chart of the API metrics data, for example, average response time
8	Representation for cache hit or miss.

APIs and Versions: On the APIs and Versions dashboard panel, you can see the following visualizations:

1	The number of requests for the top five APIs and their versions.
2	Bar-chart for the average response times for the top five APIs.
3	Donut-chart for the percentage of successful and unsuccessful API requests.
4	Line-chart for the top three API requests with comparisons of different API versions.
5	The number of API requests and the average response time for the APIs.
6	The number of API requests for the top five applications.
7	API data consumption in MB.

Developers: On the Developers dashboard panel, you can see the following visualizations:

1	Pie-chart for the top five plan usage.
2	The number of API requests for the method types.
3	The number of subscribers of an API.
4	Pie-chart for the number of requests for a subscriber.
5	The number of requests for the top five APIs.
6	Line-chart for the requests from the top three subscribers.
7	Pie-chart for the number of requests for top five applications.
8	Line-chart for requests from top three SLA plans.

Errors: On the Errors dashboard panel, you can see the following visualizations:

1	The number of errors from the top five APIs.
2	The number of errors from the top five applications.
3	Donut-chart for the number of errors from all status codes.
4	Pie-chart for the top five error types.
5	Line-chart for requests for the top five error types.
6	Line-chart for requests for all status codes.
7	List of top ten resources with the maximum number of errors.

Filtering data according to time range

In the Analytics page, you can filter the results according to a time range. There are three ways options:

Quick
Relative
Absolute

To filter the data according to time range:

Click the time filter as shown below:

Select any time range from the list, as shown below:

If you select Today, you can see the analytics of all APIs for the last 24 hours.

Click Relative. You can filter the data from a specified date and time to the current date and time.

Click Absolute. You can filter the results according to dates.

Creating a visualization

You can create your custom visualizations and save it for further analysis. Follow the steps below to create a visualization:

To create a visualization, click the Visualize tab.

You can create visualizations in the form of area charts, data table, pie charts, and so on, from API information. As an example, create a pie chart from the API analytics. Click Pie chart from the list.

Select from the following:

Create a visualization from a new search. Select From a new search. You can see a pie-chart representaion of the number of new APIs by a publisher.

Select the type of pie-chart from the following:

Split Slices
Split Chart

Select Split Slices and select Date Histogram from the Aggregation drop-down list.

Click Apply. A split pie-chart displays according to the parameters, which in this case is timestamp.

Field-based filtering

For a better perspective of the usage of your API, you can filter the dashboard according to fields. The fields can be api, version, resourcePath, and so on. When you apply the filter, the dashboard changes accordingly and you can view the graphical results.

To filter dashboard information according to fields:

Click any dashboard type:

Home
APIs
API and Versions
Developers
Errors

Choose any dashboard and hover your mouse on the graph to view the fields and the values. The snapshot below displays the field values for the top five API request count dashboard:

You can see a table that lists all the field values for a particular API and the number of times the API is called.

Click the graph. You can see the field-level filters on top of the dashboard.

Select or clear a filter and click Apply Now. You can see that all dashboards change according to the filters enabling you to have a granular view of an API. The snapshot below now represents the field values for the API usweather.

Publisher

Products Affected

In this article