Adobe ColdFusion Cold Fusion 2016 API Manager En

User Manual: adobe ColdFusion - 2016 - API Manager Free User Guide for Adobe ColdFusion Software, Manual

Open the PDF directly: View PDF .
Page Count: 127 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Legal notices
Contents
ColdFusion API Manager Overview
- Overview
Installing ColdFusion API Manager
Administrator
Publisher
Subscriber
Throttling and Rate-limiting
- Concept Overview
  - Throttling
  - Rate-limiting
- SLA configuration
Notifications
- Overview
  - Notification service
  - Notification settings
Connectors
- Overview
Setting up Cluster Support
ColdFusion and API Manager - Integration
API Manager-Metrics and Logging
Generating Swagger documents
Authentication types

"1*.BOBHFS

"%0#&¡$0-%'64*0/SFMFBTF

Last updated 2/18/2016

Legal notices

For legal notices, see http://help.adobe.com/en_US/legalnotices/index.html.

iii

Last updated 2/18/2016

Contents

ColdFusion API Manager Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Installing ColdFusion API Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5

Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Subscriber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Throttling and Rate-limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Connectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Setting up Cluster Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

ColdFusion and API Manager - Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

API Manager-Metrics and Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Generating Swagger documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Authentication types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Last updated 2/18/2016

ColdFusion API Manager Overview

Overview

The most successful companies in today's digital era create and maintain unambiguous and stable interfaces for their

business. Companies execute their strategies around extensive interfaces within and outside their enterprises. These

interfaces are known as Application Programming Interfaces (APIs).

An API-centric approach encourages evolution and management of various interfaces between systems. In this

approach, all systems are loosely coupled and allow associated services to have a wide range of uses. An API-centric

approach is similar to Service Oriented Architecture (SOA) except that APIs deal with one-to-many architectures

instead of one-one architecture of SOAs.

As a result, newer technologies, such as, REST web services make it easier to execute an enterprise API strategy.

Why API strategy

A well-planned API strategy helps businesses in executing complex software-driven strategies, such as:

•Better restructuring of internal software systems

•Reduction of maintenance costs

•Increase in agility and lean production processes

•Better customer engagement and retention

What is ColdFusion API Manager

ColdFusion API Manager helps you to create APIs that expose core functionalities of application and other backend

systems. These APIs are then published and managed at runtime.

The API Manager includes the following functionalities, such as:

•Access control: The API Manager helps you to restrict certain APIs to trusted subscribers and enforce usage for

each users based on roles.

•Analytics: You can track the usage of an API across applications, methods, and users.

•Portal: There are separate portals for an API administrator, publisher, and subscriber with custom workflows.

Last updated 2/18/2016

Architecture of API Manager

User roles in API Manager

The API Manager includes the following roles:

API Administrator-The API administrator manages and administers all core functions and properties of the API

Manager.

API Publisher-The API publisher creates an API, lists resources of each API, views all subscribed users, and analyzes

metrics of an API.

API Subscriber-The API subscriber can browse the subscribed APIs, select an API tier, create applications, and view

notifications from the publisher.

Features of API Manager

The API Manager has the following features:

Last updated 2/18/2016

Feature Description

Create an API There are multiple ways to create an API, for example:

•Manually create an API.

•Import from Swagger.

•Import internal Swagger from ColdFusion for

ColdFusion-based REST services.

•Convert a SOAP service into a REST service.

•Import a SOAP API through a proxy service.

API Versioning API versioning is essential when designing and building a REST API. As

updates are made to your APIs, you want to make sure you can make

interface changes without affecting the current usage of your API.

In the API Manager, you can create multiple versions of the same API

and manage them separately. You can later deprecate and retire a

published version.

API Security You can authenticate your API through the following security

mechanisms:

•Basic

•API Keys

•OAuth2 using SAML

Documentation The publisher can provide the complete description of an API and a

try-out tool for a subscriber to test the API.

Portal In The API Manager, there are portals to configure, publish, and

subscribe APIs, and view reports. The different types of portals are:

•Administrator portal: You can configure server

settings, SLAs, mail settings for notifications, and so

on.

•Publisher portal: You can create, publish, view, and

manage APIs.

•Subscriber Portal: You can subscribe, view, and test

an API.

Last updated 2/18/2016

Analytic Dashboards You can view metrics and API usage statistics in the API Manager via a

dashboard. There are three different types of dashboard:

•Administrator dashboard: You can analyze all the

Publishers, their API's(with versioning) and their

usage. You can take actions based on low performance

or high usage of API's and much more.

•Publisher dashboard: You can ana ly ze ov e r a l l m e t r i c s

of multiple API's(with versioning) or you can compare

your APIs (with versioning) based on factors like data

consumed/generated and usage or request-time on

time based graphs. You can take actions based on

usage, performance or load(time based) of your APIs

and much more.

•Subscriber dashboard: You can analyze the

API's(with versioning) you are subscribed to on

multiple factors like data consumed/generated or

usage or request time. Application/API based filtering

is provided. You can figure out widely used API's or

low performing API's. You can also take actions based

on API's facing throttling limit with time graphs, and

much more.

Metering and Throttling The API Manager contains a scalable metering solution that works

across all cluster nodes. The API Manager makes the asynchronous

throttle calls based on the metrics data. The API Manager manages

metering through a distributed in-memory database for real-time

control.

SLAs and Tiers The API Manager helps you create SLA tiers for your APIs by defining

the throughput and enforcing approvals.

Monitoring and Analytics The API Manager publishes all information, such as, publisher

information, subscriber information, API resources, request and

response payload, response status from end-point, response time,

response format, and SLA plan to a monitoring server. This data is

published on an analytics server within or outside a network. The

administrator, or publisher, or consumer can generate reports and

analyze the data.

Caching The API Manager contains a caching system where an API response

can be cached suitably. The caching can be enabled at subresource

level if all the resources are not cacheable at the API level.

SOAP to REST conversion The ColdFusion community develops and uses SOAP services

extensively. The API Manager helps you to wrap the SOAP services and

expose them as REST service externally. There is a wizard to help a

publisher map the SOAP input parameters to that of the REST

parameters.

SOAP Proxy Import a SOAP API through a proxy service and map SOAP endpoints

to proxy endpoints.

Clustering The API Manager helps you to set up clusters using the IP of the

machine that hosts the distributed data store services.

Last updated 2/18/2016

Installing ColdFusion API Manager

Windows

Connector In the API Manager, the connector fetches all nodes through a shared

file. A connector is by a ColdFusion server and the API Manager,

running on different machines, at the same time.

Sandbox In the API Manager, you can test your API before going to production

by configuring a sandbox URL. At runtime, based on the API key, the

API Manager calls the sandbox URL's endpoints and makes a request

to the production server. There is also a failover server, which acts as a

backup server in events when the primary endpoint server is unable to

serve a request.

Notifications You can notify users of certain events in the API Manager. For example,

•Notify a subscriber if the subscriber approaches the

end of a subscribed SLA.

•Notify a publisher to approve a subscription if

someone has made a request to subscribe to an API.

•Notify all subscribers if a publisher downgrades the

status of a published API to "Deprecate".

Last updated 2/18/2016

Linux

Mac OS X

The procedure for installing the API Manager in ColdFusion varies according to your platform (Microsoft Windows,

Linux, or Apple Mac OS X).

Windows

The ColdFusion API Manager installation wizard navigates you through the various steps of the installation process

through an intuitive user interface.

There is also an add-on installer that installs the API Manager data store and analytics server. You can install the API

Manager in one machine and the data store and analytics server in separate machines.

System Requirements

Last updated 2/18/2016

Windows

•Microsoft Windows 7, Windows 8, Windows 8.1, Windows 10, or Windows Server 2012 R2

•2 GHz or faster processor

•3-GB hard-disk space recommended

•Latest version of Google Chrome, Mozilla Firefox, or Internet Explorer browsers

To install the API Manager, you must have a Enterprise-licensed copy of Adobe ColdFusion (2016 release) Server

installed in your system.

Installing the API Manager

The ColdFusion API Manager installer is available bundled with an enterprise licensed ColdFusion (2016 release)

installer. If you run the installer, you can view the option to install ColdFusion API Manager, as shown below:

Enable the API Manager check-box and continue with the installation process. At the end of ColdFusion installation,

API Manager starts installing and you can follow the on-screen instructions.

This option is only available in Windows OS.

To inst all API Manager:

1Enter the ColdFusion instance location. For example, <ColdFusion Installation Directory>/cfusion.

2Enter the directory where you want to install API Manager.

3Choose if you want to run API Manager in the same VM as ColdFusion. Select Ye s or No.

Last updated 2/18/2016

Note: For ColdFusion installation in JEE and API manager in the same machine, if you want to run it in-VM, then add

the flag -Dapim.home in the config file of JEE application server.

4In the Port field, enter the port of the API Manager.

5Select if you want to install Analytics Server or Data Store locally or remotely. Enter the ports for the sub

components.

6Enter the administrator credentials of API Manager.

Installing API Manager add-ons

You can also install the API Analytics Server and the API Data store using an add-on installer. The size of an add-on

installer is less than the size of an API Manager installer. Choose both the options and follow the onscreen instructions.

Enter the ports for the components and click Install.

If you select Then

Yes For In-VM, API Manager services will not get created assuming that

you want to start API Manager along with Adobe ColdFusion (2016

release). After installation of API Manager, navigate to

<ColdFusion Installation Directory>/cfusion/bin and enter

cfstart.bat in the command prompt. The batch file launches API

Manager along with ColdFusion.

No After installing API Manager, services will be up and running. Open

a browser and enter http://localhost:portnumber/admin to access

Administrator portal and http://localhost:portnumber/portal to

access Publisher/Subscriber portal.

Last updated 2/18/2016

Logging in to the Administrator portal

After the API Manager installs, log in to the Administrator portal.

The Administrator portal is a platform to manage and administer properties and functionality of the ColdFusion API

Manager. Through the administrator portal, you can manage all published APIs, set up cluster and notifications, create

user and user stores, and set API authentication policies.

To log in to the Administrator portal:

1Open a browser and enter http://<locahost or IP address>:<port number>/admin

2Enter the user name and password. Click Login.

Linux

After Adobe ColdFusion (2016 release) installs, the binary file is copied in the <ColdFusion install folder> directory.

You can use the installation steps on the following OS flavors:

•Solaris

•SUSE Linux

•RHEL

•Ubuntu

Starting Adobe API Manager on Linux

1To install API Manager, enter ./ColdFusionAPIManager_2016_WWEJ_*.bin.

The * represents the OS.

2To start Data Store, navigate to <API_Manager_install_dir>/database/datastore/ and enter ./redis-server

redis.conf.properties.

3To start Analytics Server, navigate to <API_Manager_install_dir>/database/analytics/bin and enter ./elasticsearch.

Last updated 2/18/2016

4To start Adobe API Manager, navigate to <API_Manager_install_dir>/bin and enter ./start.sh.

Mac OS X

To install API Manager in Mac OS, run ./ColdFusionAPIManager_2016_WWEJ_osx10.dmg and follow the on-screen

instructions.

1To start Data Store, navigate to <API_Manager_install_dir>/database/datastore/ and enter ./redis-server

redis.conf.properties.

2To start Analytics Server, navigate to <API_Manager_install_dir>/database/analytics/bin and enter./elasticsearch.

3To start API Manager, open a browser and enter http:localhost:port/admin.

Administrator

The administrator portal is a platform to manage and administer properties and functionality of the ColdFusion API

Manager. Through the administrator portal, you can manage all published APIs, and their functional and non-

functional information.

As an administrator, you can perform the following tasks:

•Add and manage all users and their roles with respect to single or multiple published APIs.

•View and manage all SLA plans.

•View and manage tier plans of all published APIs.

Specifying server settings

Specifying security settings

Last updated 2/18/2016

Configuring SLAs

Viewing cluster information

Caching

ColdFusion discovery server

Last updated 2/18/2016

Configuring notifications

Configure log

Viewing the analytics dashboards

Logging in to the administrator portal

To log in to the administrator portal:

1Enter the user name and password in the fields provided.

2Click Login.

Last updated 2/18/2016

If you want to change the password, navigate to <API Manager Installation Directory>/conf and open the file

password.properties. Change the password in the file. You can only change the default administrator password using

the password.properties file.

Steps to reset admin password: 1. Edit the password.properties file at <apimanager_home/conf>with entries as:

adminname=<User name while installing API Manager> adminpassword=<Your new preferred password> 2. Make

readDefault to true in default_conf.xml. 3. Restart "ColdFusion 2016 API Manager" service.

You cannot delete or edit this account to remove administrator privileges.

You cannot change the password of other users except the default user.

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 file config.json.

Modify the following properties:

{

"headerTitle": "API Manager Portal",

"adminHeaderTitle": "API Manager Administrator",

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

}

Specifying server settings

You can configure the settings for the API Manager server from the following screens:

•General

•API Datastore

•API Analytics Server

General

On this page, you can set up an API Proxy or an API Portal to host your APIs.

Last updated 2/18/2016

API Proxy

In an enterprise, you communicate with existing and new customers. Consumers use a range of devices from phones

to desktops. One of the ways to interact with the devices is through an API. But, there are some concerns, for example,

security, availability, and monitoring of the APIs. In such situations, you define an API proxy. An API proxy performs

the following:

•Transports security

•Monitors SLAs, performance, and so on, of the API

•Defines access levels of an API

An API proxy makes your API independent from your back end services. Whenever you change your back end

services, for example, changes in code, the application runs without interruptions.

Setting up an API Proxy

1In the Host field, enter the IP address. The API Proxy can be a host within the network or external to the network.

2In the Port field, enter the port of the API Proxy. For example, http://localhost:5100, where 5100 is the port number.

3To enable the port on the API Proxy when the proxy restarts (manually or scheduled), select the Enable check-box.

4In the Context Root field, enter the name of the context root. A context root identifies an application on the server.

For example, if your application's context root is mycontextroot, and the application is hosted on

http://localhost:5100, you can access the application at http://localhost:5100/mycontextroot.

5In the AJP Port field, enter the port number of the Apache JServ Protocol (AJP) connector. AJP allows Tomcat to

communicate with an Apache web server.

6To enable the AJP Port on the server, select the Enable check-box adjacent to the AJP Port field. To save the changes,

click Save.

7In the Domain URL field, enter the URL of the domain that hosts the API endpoints.

Last updated 2/18/2016

Setting up a Portal

Publishers use portals to create APIs for subscribers to consume. On a portal, a publisher can create the APIs and can

restrict the APIs to certain nodes. Portals can run on multiple nodes. On the other hand, you can configure an API

proxy on any node.

1In the Port field, enter the port of the API Portal.

2To enable the port on the API Portal when the proxy restarts (manually or scheduled), select the Enable check-box.

3In the AJP Port field, enter the port number of the Apache JServ Protocol (AJP) connector. AJP allows Tomcat to

communicate with an Apache web server.

4To enable the AJP Port on the server, select the Enable check-box adjacent to the AJP Port field. To save the changes,

click Save.

API Datastore

The Datastore is a distributed configuration system and an in-memory cache used in the API Manager. The API

Datastore has the following advantages:

•Distributed

•Fast

•Scalable

•Failsafe

Last updated 2/18/2016

Configuring datastore settings

1In the Host field, enter the host name or IP address of the Data store. The Data store can be local or external to a

network.

2In the Port field, enter the port number of the Data Store.

3In the Password field, enter the password of the Data Store.

4In the Timeout field, enter the timeout duration in seconds.

API Analytics Server

Configure the settings for the number of API requests for which to generate metrics. For more information, refer to

API Manager-Metrics and Logging.

Last updated 2/18/2016

Configuring metric settings

1In the Cluster Name field, enter the name of the cluster. The analytics of these requests are then published into a

portal. For more details, refer to Setting up Cluster Support .

2In Analytics Server configuration, the client can sniff the rest of the cluster, which adds nodes that the cluster can

use. To enable the feature, select Sniff.

When you select Sniff and specify an Analytic Server address in the configuration, the API Manager finds out the

other cluster members and load balances them in a round-robin fashion.

3Specify all the node addresses along with the cluster port. To manually add the nodes, click Add Address.

4Enter the port numbers in the HTTP Port and Cluster Port fields. The Cluster Port is the location where the API

Manager sends the metric data to the Analytic Server. The analytic dashboard fetches the data from the HTTP Port.

5In the Flush Interval field, enter the time interval (in seconds). This is the time after which the Analytic Server

receives a specified number of API requests.

6In the Refresh Interval field, enter the time interval (in seconds). This is the time after which the Analytic server

refreshes one or more index.

7In the Maximum Actions Per Bulk Request field, enter the number of API requests that are collectively sent to the

analytic server for metrics calculation and visualization. If you enter 1000 in the field, no more than 1000 requests

can be sent to the server.

The default value is 1000 actions per bulk request. This means that whenever, 1000 requests are received by the API

Manager, a bulk request is dispatched to the Analytics server.

Last updated 2/18/2016

8In the Maximum Concurrent Bulk Request field, enter the number of concurrent blocks of API requests that are

sent to the analytic server. For example, if you enter 2 in the field, no more than two concurrent blocks of API

requests can be sent to the server.

9In the Maximum Volume Per Bulk Request, enter the size of the concurrent requests in this field. The size is

calculated in MBs. For example, if you enter 5 in the field, the size of concurrent API requests cannot exceed 5 MB.

Specifying security settings

Configuration

You can configure the OAuth2 settings on this screen. This protocol allows third-party applications to grant limited

access to an HTTP REST service, either on behalf of a resource owner, or by allowing the third-party application to

obtain access on its own behalf.

Configuring OAuth2 settings

1Click Security > Configuration.

2In the Encryption Seed field, enter a random string as new seed value to encrypt application keys, user store

connection passwords, and mail server passwords. This string is always a random value.

Note: If you change the encryption seed, restart the API Manager application server.

3In the Portal Session Timeout field, enter the number of seconds after which the session of an API publisher or

administrator portal application expires.

4In the OAuth2 Session Timeout field, enter the number of seconds after which your OAuth2 session gets expires.

After the session, you will enter your user name and password for obtaining access tokens and authorization codes.

Last updated 2/18/2016

5In the OAuth2 Access Token Default Timeout field, enter the duration of the default OAuth2 access token after

which the original access token expires. A subscriber can override this value in the application configuration.

6In the OAuth2 Refresh Token Default Timeout field, enter the default OAuth2 refresh token duration after which

the ioriginal refresh token expires. A subscriber can override this value in the application configuration.

7In the Authorization Code Timeout field, enter the number of seconds after which the OAuth2 authorization code

expires.

8To allow only HTTPS on OAuth2 and token endpoints, select the Mandate HTTPS check-box. If you select this

check-box, you reject plain HTTP connections.

User Store

A user store is a database to store information about users and user roles. The database stores login id, password, first

name, last name, email address, and so on.

You can create a user store through LDAP or a database connection, such as, JDBC and ODBC. The API Manager

comes with an internal user store.

To add a user store:

Creating a user store

1Click Security > User Store.

2Click Add User Store.

3From the Connector Type drop-down list, select the type of connector - LDAP Connector or Database Table

Connector.

Database Table Connector

You can create a user store using JDBC. You can create a connection string in the database to store the information that

an application uses to connect to the database.

Details tab

The Details tab contains the following fields:

Field Description

Name The name identifies the user store.

Last updated 2/18/2016

Connection tab

The Connection tab contains the following fields:

Configuration tab

The Configuration tab contains the following fields:

Pooling tab

The Pooling tab contains the following fields:

Logon Identifier The unique identifier for a user store. Prefix this identifier when you log

in to a portal.

Description The information about the user store.

Disabled check-box Select to enable users in the store access consumer applications.

Field Description

Database Server Name The name of the host from where the database runs.

Database Port The port number of the database server.

Database User Name The name of the user that has permission to a table.

Database User Password The password of the user.

Database Name The name of the database server that contains the table.

JDBC Driver The name of the class of the JDBC driver.

JDBC Connection URL The URL of the JDBC driver. For more information, refer to the JDBC

Driver documentation.

Datasource Path The path to the source of JDBC data. For example,

jdbc/SampleDataSource.

Initial JNDI Properties The list of JNDI standard environment properties.

Field Description

User Table The name of the table that contains the user accounts.

Key Column The value of the column that uniquely identifies the rows in the table.

User First Name Column The first name of the user.

User Last Name Column The last name of the user.

User Email Column The email of the user.

Password Column The name of the column in the table that holds the values of the

passwords of a user.

Roles Table The name of the table in the database that contain user roles.

Roles Table Key Column The name of the table that contains the mapping between users and

their roles.

User Roles Mapping Table User Key Column The value of the column that associates user account in the table.

User Roles Mapping Table Role Key Column The value of the column that associates roles of users in the table.

Last updated 2/18/2016

Advanced tab

The Advanced tab contains the following fields:

LDAP Connector

You can configure the API Manager to leverage an LDAP server for user authentication. In this case, the LDAP server

creates and manages users.

Details tab

The Details tab contains the following fields:

Connection tab

The Connection tab contains the following fields:

Field Description

Maximum Idle Connections The maximum number of connections to the database that can be

idle.

Minimum Idle Connections The minimum number of connections to the database that can be idle.

Connection Wait Timeout The time (in milliseconds) that the pool can wait for a connection

before it times out.

Maximum Active Connections The maximum number of connections that are allocated from the pool

concurrently.

Idle Connection Evict Timeout The time (in milliseconds) to wait before removing an idle connection.

Field Description

Enable writing empty string Select this check-box to write an empty string instead of a null value in

columns defined as not-null in the table schema.

Name Quoting Select this check-box if you want the column names for the database

to be within quotes.

Validate Connection Query The SQL query to validate the database connection.

Field Description

Name The name of the user store. The name identifies this user store.

Logon Identifier The identifier of the user store in LDAP.

Description The information about this user store.

Disabled Select this check-box to enable users in the store access the consumer

applications.

Field Description

Host The name or IP address of the LDAP server.

TCP Port The port number of the LDAP server. This port is the same as the port

on which the LDAP listens for SSL connections.

Last updated 2/18/2016

Configuration tab

The Configuration tab contains the following fields:

Advanced tab

The Advanced tab contains the following fields:

User Bind DN The bind Distinguished Name (DN) to connect to the LDAP server. The

bind DN is the user on the external LDAP server permitted to search

the LDAP directory within the defined search base. The role of the bind

DN is to query the directory using the LDAP query filter and search for

a user. For example, some possible bind DNs are cn=administrator,

cn=Users, dc=domain, or c=com.

User Bind DN Password The password to connect to the LDAP server.

SSL/TLS Enabled Select this check-box to use a secure connection.

StartTLS Enabled Select this check-box to allow an application to send secure requests

to an LDAP server.

Base Contexts The points in the LDAP tree for searching the tree.

Failover Servers The name of all the servers that act as failover servers. For example,

"ldap://ldap.example.com:389/" represents a list of failover servers. If

the primary server fails, Java Naming and Directory Interface (JNDI)

connects to the next available server in the list.

Field Description

User Configuration The object classes for creating user objects in LDAP. An object class

represents the type of data in an LDAP. An objects class contains

attributes of an entry in an LDAP. An objectclass is defined in a schema.

LDAP Filter for Retrieving Accounts The filter attribute to retrieve user accounts from LDAP.

Account User Name Attributes The attribute or attributes that represent a user name of an account.

An attribute authenticates a user name in an LDAP entry.

User First Name Attribute The attribute that represents the first name of the user in an LDAP

account.

User Last Name Attribute The attribute that represents the last name of the user in an LDAP

account.

User Email Attribute The attribute that represents the email of the user in an LDAP account.

Group Configuration The object classes for creating groups in LDAP.

LDAP Filter for Retrieving Groups The filter attribute to retrieve user groups from LDAP.

Group Name Attribute The attribute that represents the name of the group in an LDAP

account.

Group Membership Attribute The attribute that contains users in an LDAP group.

Last updated 2/18/2016

Adding users

User management in the API Manager involves defining and managing users, roles, and their access levels. You can add

or delete users, assign roles, search for users, manage user stores, and import external users from LDAP or database

connection.

To add a user :

1Click Security > Users

2Click Import External Users to retrieve users from a database or an LDAP connection.

Field Description

Use Paged Result Control Select this check-box to ensure that the LDAP uses paged results

instead of Virtual List View (VLV) when retrieving user accounts. VLV

lets you query a large directory in chunks. For example, let there be a

directory with a large number of users, "ou":

dc=demo,dc=local

+ ou=DemoGroups (100,000 groups)

+ ou=DemoUsers (100,000 users)

If you want to present the information in the user group "ou" in a

scrollable or paged window in an application, retrieving 1000 pages of

100 results each is an inefficient way. This method is resource-

intensive and wastes bandwidth. On the other hand, VLV queries a

large data-set with a sorting rule. For example, using VLV, you can sort

the first 50 users ordered by organizationName in an LDAP.

LDAP Referral Handling Either follow or ignore LDAP referrals. LDAP referrals enable an LDAP

tree to be distributed across multiple LDAP servers. Therefore, an LDAP

server can reference other LDAP servers even though it does not store

the full Directory Information Tree (DIT). When you browse a particular

directory, an LDAP server returns referrals after referring you to

another server in the tree.

Last updated 2/18/2016

3To add a user, select a user store and click Add User. The following page displays.

aIn the User Name field, enter the unique identifier of the new user.

bEnter the attributes of the user in the rest of the fields.

cSelect the appropriate role for the new user- Publisher, Subscriber, or Administrator. For more details, see Roles .

dClick Add User to add the user in the user store.

Configuring SLAs

In the API Manager, an application or a resource can be available to a consumer at different levels of service. SLA

configuration enforces access control through rate limiting and throttling. Throttling tiers limit the number of hits to

an API over a certain time, due to monetization of the API, security restrictions, infrastructure issues, and so on.

For example, you can set throttling tiers to the APIs to limit access to it accordingly. Each tier defines a maximum

number of requests per day or week or month.

You can also set the rate limit for an SLA per second or minute or hour.

You can then add your own tiers to the API Manager using the instructions below:

Adding an SLA

1Click SLA Configuration. The following page displays.

Last updated 2/18/2016

2Select the rate limiting algorithm. In API manager, two types of algorithms can be used to limit the rate: Rolling and

Fixed.

In fixed window algorithm, the period is considered from the starting of the time unit to the end of the time unit.

For example, a period is considered as 0-60 seconds for a minute irrespective of the time frame at which the API

request has been made.

In rolling window algorithm, the period is considered from the fraction of the time at which the request has been

made to the end of the time unit. For example, if two requests for API calls are made at 30th second and 40th second

of a minute it is considered as two requests from 30th second of that minute up to the 30th second of next minute.

For more details, refer to Throttling and Rate-limiting.

3In the SLA Name field, enter the name of the new SLA.

In the Rate Limit field, enter the API request rate limit in the SLA. You can only limit an API request rate to number

of requests per second, minute, or hour.

In the Throttle Limit field, enter the API throttle limit in the SLA. You can only limit an API request rate to number

of requests per second, minute, or hour.

Last updated 2/18/2016

Select the type of throttle limit- Hard or Soft.

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

4In the Notify Limit field, enter the limits (in percentage) at which you receive notifications when the number of API

requests approach the limit.

5In the Exceed Limit field, enter the limits (in percentage) by which the number of API requests can exceed.

6If the SLA requires an approval from the API publisher, select the Approval Required check-box.

Editing an SLA

You can edit an SLA and modify its properties. Choose an SLA from the Existing SLAs list.

1Click Edit. The following page displays.

2Update all the properties of the SLA and click Update SLA.

Viewing cluster information

You can see a list of all clusters configured in API Manager. You can also see a cluster's proxy port, portal port, and so on.

Last updated 2/18/2016

Caching

Set the maximum response size to define the maximum size, in bytes, of the response that can be stored in the output

cache. Also specify the timeout, in seconds.

ColdFusion discovery server

If you want to discover REST services published in a ColdFusion non-InVM environment, configure the ColdFusion

server on the CF Discovery Server Configuration page.

1In the Protocol drop-down list, select HTTP or HTTPS.

2In the Name field, enter the name of the ColdFusion server.

3In the Address field, enter the host and port number of the CF server.

4In the Context field, enter the REST servlet context of the CF server.

5In the Username and Password fields, enter the credentials to log in to the ColdFusion server.

Last updated 2/18/2016

Configuring notifications

The API Manager sends notifications for any alerts or user events that require attention. You can configure the settings

for email notifications for publishers and consumers.

Configuring mail settings

1Click Notifications > Mail. The following page displays.

2In the Mail Server field, enter the name of the server that sends Simple Mail Transfer Protocol (SMTP) messages.

Alternatively, you can enter the mail server (for example, mail.company.com) or the IP address of the mail server

(for example, 127.0.0.1).

3In the Port field, enter the port number of the mail server.

4In the Username and Password fields, enter the credentials to authenticate a user in the mail server.

5In the Timeout field, enter the time (in seconds) that the API Manager waits for a response from th email server.

6In the Protocol field, enter the messaging protocol for the mail server, for example, SMTP.

7To enable Transport Level Security (TSL) on the connection to the mail server, select the Enable TLS connection to

mail server check-box. Transport Layer Security (TLS) is a protocol that ensures privacy between applications and

their users within a network. When a server and client communicate, TLS ensures security of the communication.

Configure log

In this page, choose the modules for which you want to generate debug logs. For example,

•Messages logged during startup, shutdown, and cluster updates.

Last updated 2/18/2016

•Messages logged when a request is dispatched.

•Messages logged when an API resolves a request.

You can enable debugging for specific sections that you want to debug. For example, if you want to check for any issues

while creating an API, enable the Publisher check-box in the Portal section.

This way you can manage your debug logs properly.

Viewing the analytics dashboard

Analytics dashboard helps you view the number of APIs that are run from a node, the number of API requests, and

system statistics. The API Manager collects information as APIs process information. If you see a sudden spike on a

graph or chart, you can take immediate measures.

By clicking a particular data (for example, API name or Publisher name or field in graph), you can filter the entire

dashboard on that field.

Click Analytics to display the dashboard.

There are three types of dashboards in the Administrator portal:

•Home

•Publisher APIs

•Publishers

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

Request Count for Nodes

You can view the node IP and port on which an API runs. You can also view the number of requests by the API. Hover

the pointer on the visualization to see the details.

Last updated 2/18/2016

Total Request Count

You can view the count of requests by an API.

Consumed Metrics

You can view the avarage response time (in milliseconds) of an API, and the average incoming and outgoing data (in

KB) of the API.

Last updated 2/18/2016

Average Request Count

You can view a line graph of the count of API requests. You can further filter the data according to the time range, for

example, today, this week, this month, last minutes, last 30 minutes, last 5 years, and so on. Hover the pointer on an

point on the axis to view the number of API requests within the time range.

Last updated 2/18/2016

Average Response Time

You can view the average response time of an API using this visualization. This time is in milliseconds. You can filter

the data according to a time range.

Last updated 2/18/2016

Publisher APIs: On the Publisher APIs dashboard, you can see the details of each API from a publisher, the number

of APIs, the number of publishers, the response times for APIs, and so on.

You can filter the requests and whole dashboard on the publishers.

Hover the pointer on a pie chart or a line chart to view more details.

1Pie-chart for the number of API requests by publishers.

2The number of API requests by a publisher.

3The number of API requests.

Last updated 2/18/2016

Publishers: On the Publishers dashboard, you can see the visualization of the number of API requests, the number of

publishers, average data consumption per publisher, and so on.

You can filter the requests and whole dashboard on the publishers.

Hover the pointer on a pie chart or a line chart to view more details.

Creating a visualization

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

visualization:

1To create a visualization, click the Visualize tab.

2You can create visualizations in the form of area charts, data table, pie charts, and so on, from API information. As

an example, create an area chart from the API analytics. Click Area chart from the list.

4The number of APIs.

5The number of nodes in a cluster that contains the APIs.

6The number of publishers.

1Pie-chart for the number of API requests by publishers.

2The number of nodes in a cluster that contains the APIs.

3The number of API requests.

4The unique count of publishers that have made at least one request

within the time range.

5The number of API requests from all publishers.

6The number of API requests by publishers according to time-range.

Last updated 2/18/2016

3Select from the following:

4Create a visualization from a new search. Select From a new search. You can see the following index patterns in the

drop-down list:

5Select the data point on the X-Axis and click Apply.

Last updated 2/18/2016

An area chart displays with number of API requests on the Y-axis and API time-stamp on the X-axis.

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:

1Quick

2Relative

3Absolute

1Click the time filter as shown below:

Last updated 2/18/2016

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

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

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

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:

Last updated 2/18/2016

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.

1Click Create REST API. The Basic Settings page displays.

Last updated 2/18/2016

2Enter the following details in the Basic Settings section.

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

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

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.

Last updated 2/18/2016

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

Last updated 2/18/2016

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

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

Last updated 2/18/2016

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:

1Enter 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

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

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

4To 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).

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

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

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

Last updated 2/18/2016

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:

Last updated 2/18/2016

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.

Last updated 2/18/2016

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

Last updated 2/18/2016

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.

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

•API Name

•Context

•Visibility

•Version

•Description

•WSDL URL

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

Last updated 2/18/2016

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.

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

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

Last updated 2/18/2016

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.

Last updated 2/18/2016

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

5To gene rate 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 c a n s e e t he f o l l ow i n g :

Last updated 2/18/2016

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

You c a n s e e t he f o l l ow i n g :

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

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

Last updated 2/18/2016

8Click Publish to make the REST API available to subscribers.

Note: The SOAP to REST feature does not support the WS-* SOAP specifications, for example:

•WS-Addressing

•WS-Policy

•WS-ResourceProperties

•WS-Security

•WS-Transactions

•WS-ReliableMessaging

•WS-ResourceLifetime

Note: For some SOAP services, resources that do not get converted to REST out of the box, write your own mechanism to

convert to REST.

Importing REST API from ColdFusion

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

API Manager - Integration.

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.

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

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

Last updated 2/18/2016

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

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

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

3Enter the API information and set the visibility.

4Set the authentication type for the API.

Last updated 2/18/2016

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

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

1In the API Manager, click Import SOAP API.

Last updated 2/18/2016

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

3Click 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,

Last updated 2/18/2016

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

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

Last updated 2/18/2016

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 .

6To 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:

1apiKey

2basicAuth

3OAuth2

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

basicauth

Last updated 2/18/2016

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.

1From the User Store drop-down list, select a user store. The API administrator creates a user store.

2Create a scope. A scope defines a role defined in a user store. Enter the name of the scope and select a role.

3To 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,

1Select an Oauth type, USERSTORE or SAML. If you select USERSTORE, select a user store defined in LDAP or

database connection.

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

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.

Last updated 2/18/2016

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

1Select any plan created by the administrator.

2Click the name of the plan and change its properties.

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

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

5Select the type of limit for the API requests.

Last updated 2/18/2016

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.

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

7To 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:

1Enter the number of requests for an SLA plan.

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

Last updated 2/18/2016

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.

Last updated 2/18/2016

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.

Last updated 2/18/2016

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:

Last updated 2/18/2016

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

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

1The number of API requests within a time range with total requests

and erroneous requests.

2A donut-chart representation of API success and errors.

3The metrics data like average response time, number of API requests

for APIs, and so forth.

4The average response time of an API in milliseconds.

5Cache hit or miss.

6Line chart of successful and unsuccessful API requests.

1The number of requests for the top five APIs and the versions.

2Donut-chart for the number of API requests by the top five

applications.

3Donut-chart for the percentage of successful and unsuccessful API

requests with comparison of the versions of an API.

4Bar-chart for the average response time for an API.

5Line-chart for the number of requests by the top three APIs.

6The number of API requests.

7Donut-chart of the API metrics data, for example, average response

time

8Representation for cache hit or miss.

Last updated 2/18/2016

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

1The number of requests for the top five APIs and their versions.

2Bar-chart for the average response times for the top five APIs.

3Donut-chart for the percentage of successful and unsuccessful API

requests.

4Line-chart for the top three API requests with comparisons of different

API versions.

5The number of API requests and the average response time for the

APIs.

6The number of API requests for the top five applications.

7API data consumption in MB.

1Pie-chart for the top five plan usage.

2The number of API requests for the method types.

3The number of subscribers of an API.

Last updated 2/18/2016

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

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:

1Quick

2Relative

3Absolute

To filter the data according to time range:

1Click the time filter as shown below:

4Pie-chart for the number of requests for a subscriber.

5The number of requests for the top five APIs.

6Line-chart for the requests from the top three subscribers.

7Pie-chart for the number of requests for top five applications.

8Line-chart for requests from top three SLA plans.

1The number of errors from the top five APIs.

2The number of errors from the top five applications.

3Donut-chart for the number of errors from all status codes.

4Pie-chart for the top five error types.

5Line-chart for requests for the top five error types.

6Line-chart for requests for all status codes.

7List of top ten resources with the maximum number of errors.

Last updated 2/18/2016

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

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

4Click 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:

1To create a visualization, click the Visualize tab.

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

Last updated 2/18/2016

3Select from the following:

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

5Select the type of pie-chart from the following:

•Split Slices

Last updated 2/18/2016

•Split Chart

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

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

Last updated 2/18/2016

Subscriber

The API Manager-Subscriber portal enables an API subscriber perform the following:

•View all published APIs

•View all subscribed APIs

•Search for APIs and view them according to category

•View the parameters that an API requires

•Generate an API key

•Choose an SLA tier

•Create applications

•View notifications from publisher

Logging in

To log in to the subscriber portal:

1Enter <localhost or IP address>:<port number>/portal/ in the address bar of a web browser.

2Enter the user name and password.

3Click Login.

Browse APIs

After successfully logging in to the portal, you can view the list of subscribed APIs.

1Choose any API.

2On the API Details page, you can view the description of the subscribed API, including:

•Name and description of the API

•Version of the API

•Visibility of the API

•Context of the API

Last updated 2/18/2016

•Lifecycle of the API

3Choose any API. To try out the API, click Try Out. Select the application and the response content type. Click Run

API call. You can see the following results.

Viewing all APIs

In this page, you can view all APIs you have subscribed to.

API Catalog

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

APIs along with their version, visibility, description, and so on.

Last updated 2/18/2016

Using a REST API from ColdFusion server

Once a publisher creates an API from a ColdFusion server, you can consume and test the API.

1Choose the API from the API catalog.

2Click Resources on the left panel to view the API details.

Last updated 2/18/2016

3To test the API, cli ck Tr y Out. Choose an application and click Run API Call. You can see the API returns the

current date. Expand the Request Details and Response Details tabs to view the URL and status code.

Consuming a Swagger API

Once an API publisher publishes a Swagger API, you can test the API and use the API in your applications. Go to the

API catalog to view a list of all public APIs you can use.

1Choose the API from the API catalog.

2Click Resources on the left panel to view the API details.

3Choose a method for a resource to test the API.

Last updated 2/18/2016

4To test the API, cli ck Tr y Out. Enter the value of petid and select an application. Click Run API Call.

You can see the JSON-formatted response of the API call. For example,

Last updated 2/18/2016

Consuming a SOAP API

Once an API publisher publishes a SOAP API, you can try the API and use the API in your applications. Go to the API

catalog to view a list of all public APIs you can use.

1Choose the API you want to tryout from the list of APIs.

2Click Test t his AP I from the left panel of the API details screen.

Last updated 2/18/2016

3You can see the proxy WSDL, WSDL port type, and the operation. You can also see the REST endpoints and their

bindings. Choose the appropriate SOAP type.

4Enter a BLZ code in the SOAP body and choose an application. For example, enter the BLZ code 50040000. Click

Run API Call.

Last updated 2/18/2016

You can see the SOAP API returns the name of the bank that has the BLZ code 50040000. The response is as follows:

<?xml version='1.0' encoding='UTF-8'?>

<soapenv:Envelope

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">

<soapenv:Body>

<ns1:getBankResponse

xmlns:ns1="http://thomas-bayer.com/blz/">

<ns1:details>

<ns1:bezeichnung>Commerzbank</ns1:bezeichnung>

<ns1:bic>COBADEFFXXX</ns1:bic>

<ns1:ort>Frankfurt am Main</ns1:ort>

<ns1:plz>60005</ns1:plz>

</ns1:details>

</ns1:getBankResponse>

</soapenv:Body>

</soapenv:Envelope>

Creating an application

You can create an application and get your API subscribed to the application. Enter the name and description of the

application you want to create and click Create Application.

You subscribe to a published API before using it in your applications. Subscription enables you to receive access tokens

and be authenticated to call the API.

Last updated 2/18/2016

Subscribing to an application

Once you create an application, you need an API to subscribe to the application. Choose the API and click Subscribe

on the left pane. Select the application and choose the SLA plan. Click Subscribe. The publisher chooses the SLA plans

for you.

You can see a list of applications that are waiting for approval from the API publisher. You can also modify and delete

a subscription.

Authorizing scope at application level

Last updated 2/18/2016

As a subscriber, you can select an application and restrict its scope.

1To subscribe to an application, click Subscribe.

2To see the security keys of the application, click Applications.

1Name of the application.

2This is an application key for a resource that has authentication of

type apikey. When this key is used, the production endpoint of the

API receives the request.

3This is same as application key, but when this key is used, sandbox

endpoint of the API receives the request.

4The client ID uniquely identifies the application and is used when

there is an authentication type of basic or Oauth2.

5Client secret is used when authentication type is Oauth2 when

obtaining the token using authorization code grant or client

credentials flow. This must be kept secret.

Last updated 2/18/2016

Note: Security Considerations- Items 2, 3, and 5 must be kept secret and not be exposed outside. If any of these get

compromised, regenerate the keys so that the previous compromised keys get invalidated. Use the newly generated

credentials in your application. When passing the credentials, use HTTPS.

The Refresh Token Lifetime is always greater than the Access Token Lifetime.

IDP Metadata URL: Specifies the metadata URL of the SAML identity provider. If any of the APIs subscribe using

SAML and OAuth authentication, and your IDP hosts the metadata, enter the IDP URL here.

IDP Raw Metadata: Same as above. If you have the identity metadata, paste the XML here.

Only those tiers or usage plans associated with an approval goes to the publisher. The rest is auto-approved.

Authenticating API at subscription level

You can only make an API request once the administrator approves your subscription request. The following image

represents the API subscription approval from the publisher.

Once the publisher approves your application request, you can see the application key. You can use this key to make the

request.

Viewing the analytics dashboard

The analytics dashboard for a subscriber consists visualizations for the number of applications, number of API requests,

and API errors. Click Analytics to launch the Subscriber analytics dashboard page.

Last updated 2/18/2016

There are three types of dashboards in the Subscriber portal:

•Applications

•Subscriptions

•Errors

Applications: On the Applications panel, you can see the following visualizations:

Subscriptions: On the Subscriptions panel, you can see the following visualizations:

1Pie-chart for the number of requests for applications.

2The number of API requests.

3Line-chart for the number of application requests.

4Line-chart for the average data consumption by the applications.

5Line-chart for average response times for applications.

Last updated 2/18/2016

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

1Pie-chart for the number of requests for subscriptions (applications

and API).

2The number of API requests.

3Pie-chart for the number of requests for SLA plans.

4Line-chart for the number of requests for subscriptions (applications

and API).

5List for maximum throttling limit per SLA plan.

6Line-chart for average data consumption.

7Line-chart for average response time for subscriptions.

1The number of errors for subscriptions and SLA plans.

2The number of errors for different status codes.

Last updated 2/18/2016

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:

1Quick

2Relative

3Absolute

To filter the data according to time range:

1Click the time filter as shown below:

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

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

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

3Line-chart for requests for all status codes.

4Pie-chart for the top five types of error.

5List for top ten resources with maximum number of errors.

Last updated 2/18/2016

Throttling and Rate-limiting

Concept Overview

Throttling

Throttling is a process that is used to control the usage of APIs by consumers during a given period. You can define

throttling at the application level and API level. Throttling limit is considered as cumulative at API level.

Administrators and publishers of API manager can use throttling to limit the number of API requests per

day/week/month. For example, you can limit the number of total API requests as 10000/day.

When a throttle limit is crossed, the server sends 429 message as HTTP status to the user with message content as "too

many requests".

Throttling in API manager can be of two types: Hard and soft.

Hard: The number of API requests cannot exceed the throttle limit.

Soft: In this type, you can set the API request limit to exceed a certain percentage. For example, if you set the exceed

limit to 90%, user gets a notification when the exceed limit is crossed.

Rate-limiting

Rate-limiting is a process that is used to define the rate at which consumers can access APIs. Also, it determines the

speed at which a consumer can access APIs. Rate limit is calculated in real time.

Rate-limiting is applicable to resources. For example, in the following endpoint URL, "http://endpointurl/products",

"/products" is a resource. It can be configured or over-ridden resource level.

You can add rate limits to API resources for the SLA plans to which the APIs are subscribed. Once the API exceeds the

rate limit, the subscriber gets Status 429 message in the response header. Status 429 message indicates that the rate-limit

has crossed.

For more information on adding rate limits to API resources, refer Adding rate limits to API resources section in

Publisher document. Publisher assigns multiple plans for APIs while publishing them. Subscriber can select one of the

plans while consuming APIs.

Administrators and publishers of API manager can use rate limiting to define the number of API requests per

second/minute/hour. For example, if you set the rate as 5 req/sec, the speed at which a consumer can access each API

can be high.

If API Manager is deployed in a cluster, the rate-limit is considered across the nodes. The consumer gets an error

message whenever the defined limit is crossed within a single node or across a combination of nodes.

In API manager, two types of algorithms can be used to limit the rate: Rolling and Fixed.

In fixed window algorithm, the period is considered from the starting of the time unit to the end of the time unit. For

example, a period is considered as 0-60 seconds for a minute irrespective of the time frame at which the API request

has been made.

In rolling window algorithm, the period is considered from the fraction of the time at which the request has been

made to the end of the time unit. For example, if two requests for API calls are made at 30th second and 40th second of

a minute it is considered as two requests from 30th second of that minute up to the 30th second of next minute.

Last updated 2/18/2016

Consider an illustration as follows:

Let us assume there is a rate limit as 2 req/sec. In the above snapshot, you can notice two requests/occurrences before

1.0 second and two more occurrences after 1.0 second.

If you apply fixed window algorithm to this illustration, then two requests/occurrences are considered within 1 second.

If you apply rolling window algorithm, then four occurrences are considered within 1 second.

SLA configuration

SLA configuration in API manager enforces access control to the users through rate-limiting and throttling. For

instructions to configure SLA as an Administrator, refer to the Administrator document .

As a publisher, you can create a subscription plan and assign throttling limits to an API. For more information on

specific instructions, refer to Add tiers to an API section of Publisher document .

Notifications

Overview

The API Manager sends notifications for any alerts or user events that require attention.

The are two ways through which a user can view the notifications:

1When users log in to their respective portals, the notifications display on the portal

2Users receive an email.

On the portal, the administrator, publisher, or the subscriber can view the notifications related to scenarios, such as:

•Request to approve API subscription

•Approved API subscription

Last updated 2/18/2016

•Termination or deprecation of an API

•Errors in API endpoints

•An SLA reaches its limits

•High CPU and memory usage

•System level messages

Notification service

The notification service in API Manager dispatches messages generated from various modules (security, tier, resources,

and so on) to the intended recipients.

Alternatively, if the notifications are not configured, the notification service uses the default settings to send messages

to various recipients.

Notification settings

You can configure the notification service at two levels:

•User level: User level notification settings allow you to control the events and channels to receive notifications. The

notifications can be edited in respective user portals.

•System level: System level settings allow you to control the deletion of notifications from a list. You can set a limit

on the number of messages (for example, retain only the ten most recent messages).

Connectors

Overview

In the API Manager, connectors redirect the requests from web servers to application servers. Connectors also provide

load balancing between various nodes in a cluster. Web server connectors in the API Manager manage the

communication between the web server and the application server.

For Internet Information Services (IIS), the connector is isapi_redirect. On the other hand, for Apache web server, the

connector is mod_jk.

Last updated 2/18/2016

In the API Manager, the connector communicates with a single cluster and a ColdFusion instance or cluster, if present.

To configure the same connector for API Manager and ColdFusion, make sure that the wsconfig folder of API Manager

is present inside <cf_home>/<some-folder>. For example, C:\ColdFusion2016\apim\wsconfig.

Also copy the cluster.xml in the wsconfig folder file if you want to run wsconfig from outside the API Manager folder

structure.

Connectors also refresh the information of a cluster dynamically. You need not restart the web server. There are some

limitations:

•You c a n n ot a d d a c l us t e r.

•You can only add a node to a pre-configured cluster.

•You cannot modify the information of an existing node.

Configuration files

Connectors in the API Manager use the following configuration files:

•worker.properties: This file contains information about all application servers and clusters.

•uriworkermap.properties: This file contains rules of when to redirect a client request. This file also contains uri

prefixes and filename extensions mapped to application servers or clusters defined in the file worker.properties.

Configuring connectors using Wsconfig tool

You can use the Wsconfig tool to configure connectors. The Wsconfig tool supports both a Graphical User Interface

(GUI) and a Command Line Interface (CLI). You can configure the connectors in the API Manager and ColdFusion,

if installed.

Last updated 2/18/2016

The Wsconfig tool reads the configuration files and configures the connectors based on some parameters. You can use

this tool to add or remove a connector. This tool can be run from any server, but it requires a configuration file to get

the information about a cluster and its nodes.

You can refresh information in a cluster after adding a node. Enter wsconfig -help in the command prompt and view

the parameters for refresh.

Note: To serve PUT and DELETE requests through connector in IIS, remove the following:

1webDAVModule from IIS > Modules

2WebDAV from IIS > Handler Mapping in IIS Manager

Configuring IIS

1 Click Start > Control Panel. Select Programs and Features.

2Click Turn Windows features on or off.

3Select Internet Information Services > World Wide Web Services > Application Development Features.

Last updated 2/18/2016

Select the following check-boxes:

•ASP.NET

•CGI

4In the <API Manager Installation Directory>/wsconfig/ directory, double-click wsconfig.exe.

5Click Add.

6From the IIS Web Site drop-down list, select Default Web Site. Click OK.

7Restart the server. Click Yes.

The default IIS server becomes the default web site.

Last updated 2/18/2016

8To verify the successful installation of the connector, enter <localhost>:80/portal in the address bar of a web

browser.

Note: The Administrator is blocked in the web server. To access the portal, use the port, 9000.

To configure a web server on a remote machine, copy the cluster.xml file to the folder <API Manager installation

directory>/conf/. Start the API Manager first and then run the wsconfig tool.

Configuring Apache

1In the <API Manager Installation Directory>/wsconfig/ directory, double-click wsconfig.exe.

2Click Add. On the Add Web Server Configuration dialog box, select Apache from the Web Server drop-down list.

3Restart the server. Click Yes.

Last updated 2/18/2016

The Apache server becomes the default web server.

You can configure connectors for a particular Apache Virtual Host, similar to IIS. The Virtual Host serves requests only

to the API Manager, not to any non-API Manager configurations.

Note: If you use the command line, specify -vhost <virtual_host_name>. The parameter is mandatory.If you do not have

a virtual host or you want to install Apache globally, use -vhost All in the command line.

Setting up Cluster Support

Overview

A cluster consists of a set of objects that act as a single instance, and divide the workload. Clustering improves

performance as the requests are distributed across several objects. Clustering also improves reliability because if one

object instance is unavailable or experiencing high traffic, other instances can handle the request.

The API Manager provides cluster support for application scaling and high availability. As an administrator, you can

create a homogeneous cluster for scaling and availability for your APIs via the API Manager.

Starting a cluster

To start a cluster in the API manager:

?Change <cluster><enabled>false</enabled></cluster> to <cluster><enabled>true</enabled></cluster>.

To add a node to the cluster, start the node on a separate port. Any change in the API information in one node reflects

in all nodes within a cluster.

If you add a new node to the cluster, perform the following SAML-related tasks:

1Copy the file seed.properties to the new node. You can locate the file in {API Manager_HOME}/conf/.

2Copy the file samlspcerts.jks to the new node. You can locate the file in {API Manager_HOME}/conf.

3Copy the following snippet in the config.xml file to the new node. You can locate the file in {API

Manager_HOME}/config.

Last updated 2/18/2016

<path>C:\ColdFusion2016APIManager\conf\samlspcerts.jks</path>

<samlspalias>ampserviceprovider</samlspalias>

</keystore>

Using the API Manager data store for clustering

When installing API Manager, you can opt to install the API Manager data store. All API Manager nodes that are a part

of a cluster share a common data store. This server stores all configuration-related information of the API Manager. All

nodes connected to the server share similar configuration.

Each server in the API Manager has its own cluster configuration. This configuration retrieves the connection details

from the data store when a node starts up. In a clustered environment, the API Manager node connects to the server

defined in the cluster configuration.

Accessing a node in Redis

By default when Redis is installed, it is reachable only through localhost (127.0.0.1). To access it from a remote machine,

perform the following steps:

1Navigate to <API Manager installation directory>\database\datastore and open the file

redis.windows.conf.properties. In case of Linux, it is redis.conf.properties.

2Specify the host name or IP address of the Redis data store in the bind section so that it can be accessible to remote

API Manager nodes. You also perform this step when installing an API Manager node on a machine other than

Redis datastore machine.

Viewing the cluster via the portal

You can view the cluster via the Administration portal if you install the API Manager stand-alone in your computer.

On the Admin portal, you can view the details of the data store to connect to.

On the Cluster Configuration page in the Administrator portal, you can view the list of nodes that are a part of a cluster.

This information persists as part of the node configuration.

Last updated 2/18/2016

Accessing a node in Elastic Search

To access Elastic Search from a remote machine, perform the following steps:

1Navigate to <API Manager installation directory>\database\analytics\config and open the file elasticsearch.yml.

2Specify the host name or the IP address of the Elastic Search server in the network.host section so that the address

is accessible to remote API Manager nodes.

Fault tolerance through clustering

Since clustering in the API Manager is homogenous, APIs published from one node are published from all nodes in the

cluster. If any node fails, there is no impact on availability of the published APIs.

ColdFusion and API Manager - Integration

Overview

API Manager facilitates the management of APIs that are exposed through REST or SOAP services. To experience

seamless integration with ColdFusion APIs, you can access ColdFusion REST services from API Manager.

The admin portal available with the API Manager lets you define the ColdFusion discovery server. Once such a

ColdFusion discovery server is set, you can readily import REST services defined in the ColdFusion server with just a

single click. With minimal configuration, you can readily publish the APIs associated.

Starting API Manager with ColdFusion

You can start API Manager from ColdFusion in either of the following ways:

•Provide ColdFusion's home directory while installing API Manager.. API Manager is installed in a separate

directory.

•Provide the –Dapim.home={application-home} flag in <ColdFusion Home>.

Discover ColdFusion REST services from API Manager

Last updated 2/18/2016

InVM

If you start API Manager along with ColdFusion, the API Manager detects REST services that are published in

ColdFusion.

Publisher can import these REST services from the “In VM” category in the Import screen as shown below:

Note: This category appears only when API Manager is started with ColdFusion.

Remote

If you have already installed API Manager and you want to discover REST services published in a non-InVM

ColdFusion, add the ColdFusion server configuration according to the following steps:

1Start API Manager in Administrator mode.

2Click CF Discovery Server Configuration on the left pane.

3Add the configuration values.

Last updated 2/18/2016

Set API Manager flags in ColdFusion

From ColdFusion Administrator > Settings page, you can set the flag for REST discovery service as shown in the

following screenshot.

If you select the Allow REST Discovery check box option, then API Manager discovers REST services automatically.

If you clear this option, then REST services do not appear in API Manager's Publisher page while importing APIs.

Note: If you clear this check box during CF startup and enable later, you can perform one of the following:

•Restart the ColdFusion server.

•Reinitialize the REST service to make the service available in API Manager.

API Manager-Metrics and Logging

Overview

ColdFusion API Manager collects and analyzes information that APIs generate. This information is useful to measure

the performance of APIs. The information provided by the API Manager can be used to make decisions, such as:

•Change in any API.

Last updated 2/18/2016

•Applications that are consuming an API for the maximum or minimum time.

•HTTP methods (GET, PUT, POST, and so on) that have maximum usage.

•Capacity planning of APIs.

Metrics

When an API makes a runtime request to the API Manager, the analytic server pulls the following information from

the request, such as:

•Timestamp

•API Name

•Version

•Publisher

•Consumer

•Application

•SLA

•Error

•Request Method

•Status Code

•Request Content Size

•Response Content Size

•Request Time

•Sub resource pattern

•Request Content-Type

•Response Content-Type

•Cluster Node Name

•Request IP

To view the analytics, a publisher, consumer, or an administrator has access to a dashboard. Publishers and

administrators have their own personal dashboards which they can edit and add a visualization, dashboard, and so on.

But dashboards for consumers cannot be personalized.

This dashboard is a web interface that publishes metrics analytics and log information in the form of graphs and pie

charts.

Modify metric settings

As an administrator, you can configure the settings for the number of API requests for which to generate metrics. On

the Administrator portal, select Server > API Analytics Server Configuration to display the Metric Settings page.

Last updated 2/18/2016

Cluster Name- Enter the name of the cluster in which the APIs make the request. The analytics of these requests are

then published into a portal. For more details, refer to Setting up Cluster Support.

Sniff-In Analytics Server configuration, the client can sniff the rest of the cluster, which adds nodes that the cluster can

use. To enable the feature, select Sniff.

Flush Interval- Enter the time interval, in seconds, after which the ElasticSearch server receives a specified number of

API requests.

Maximum Actions Per Bulk Request- Enter the number of API requests that are collectively sent to the ElasticSearch

server for metrics calculation and visualization. If you enter 1000 in the field, no more than 1000 requests can be sent

to the server.

Maximum Concurrent Bulk Request- Enter the number of concurrent blocks of API requests that are sent to the

ElasticSearch server. For example, if you enter 2 in the field, no more than two concurrent blocks of API requests can

be sent to the server.

Maximum Volume Per Bulk Request- Enter the size of the concurrent requests in this field. The size is calculated in

MBs. For example, if you enter 5 in the field, the size of concurrent API requests cannot exceed 5 MB.

Log analysis in API Manager

A user (publisher or administrator or subscriber) can view the information that the API Manager logs.

Since the API Manager is a multi-tenant system, multiple publishers can use platform concurrently. So when a

publisher retrieves the logged information, the API Manager retrieves those logs that are specific to a publisher. It is

more secure since first publisher has no access to the second publisher's logs.

Last updated 2/18/2016

On the dashboard, the publisher can view and analyze logs using certain filters, such as:

•Logs in last 15 mins/30 mins/last day/last month/any custom time

•Error logs

•Logs from a specific consumer

•Logs for a particular service or a version

•A combination of one or more filters

Generating Swagger documents

Overview

Swagger is a project specification that is used to describe and document RESTful APIs. In Adobe ColdFusion (2016

release), you can create swagger doc automatically from REST CFC after it is implemented and registered in server. The

Swagger version that is supported in ColdFusion is 1.2.

For more information on Swagger project overview, refer to Swagger documentation. Swagger specification 1.2 is

available here.

Document generation process

The Swagger doc generation feature is a part of ColdFusion Server. ColdFusion server generates the Swagger doc

automatically once you register REST CFC application.

Create your REST CFC file

You can create REST CFC application file of your choice and place this file in the root folder (wwwroot) of ColdFusion

server. A sample CFC file content structure is shown in the following studentservice.cfc file.

Last updated 2/18/2016

<cffunction name="addStudent" access="remote" returntype="void" httpmethod="PUT"

description="add student">

</cffunction>

<cffunction name="addStudents" access="remote" returntype="void" httpmethod="POST"

description="add students">

</cffunction>

<cffunction name="deleteStudent1" access="remote" returntype="void" httpmethod="DELETE"

description="delete students">

</cffunction>

<cffunction name="updateStudentAddress" access="remote" returntype="address"

httpmethod="POST" restpath="{studentId}" description="modify student address" hint="modify the

address for given studentId">

</cffunction>

<cffunction name="getStudent" access="remote" returntype="Student" restpath="{name}-{age}"

httpmethod="GET" description="retrieve student" produces="application/json"

responseMessages="404:Not found,200:Successfull:student" >

<!--- Create a student object and return the object. This object will handle the

request now. --->

</cffunction>

</cfcomponent>

Using application.cfc file

If you do not want the ColdFusion server to generate swagger doc automatically, set the following code to false in

application.cfc file. Refresh the registered application in CF administrator.

A sample application.cfc file is shown below for your reference.

Last updated 2/18/2016

</cfcomponent>

Using new response messages attribute

A new attribute named responseMessages has been introduced in Adobe ColdFusion (2016 release). You can use this

attribute in REST CFC file as shown in the sample file below.

<cffunction name="sayPlainHelloUser" responseMessages="404:Not

Found,200:successful,10:notdefine" access="remote" returnType="String" httpMethod="GET"

produces="text/plain">

<cfargument name="nAme" type="string" restargsource="cOOkie" required="false"

default="CF">

</cffunction>

</cfcomponent>

The swagger API document generated from this sample responseMessages code appears as shown below.

Start ColdFusion Administrator. Click Data & Services > REST Services on the left pane and add configuration values

as per the instructions in the following dialog.

100

Last updated 2/18/2016

1Enter the root path where REST CFCs are available in your system. Alternatively you can click Browse Server and

choose the path where the CFC application resides.

2Enter the host name for the REST service. For example, localhost:8500

3Enter the Service Mapping string name. For example, http://localhost/rest/{service mapping}/test

4Select the check box if you want to set the application as default while calling the web service.

Access swagger api-docs

The Swagger representation of the API comprises two file types:

The Resource Listing - This root document contains general API information and lists the resources. Each resource

has its own URL that defines the API operations on it.

The API Declaration - This document describes a resource, including its API calls and models.

You can verify the ColdFusion generated swagger APIs document by using the ColdFusion server path as follows:

You can access resource listing by using the same path as above without the resourcePath name. (<ColdFusion server

URL path:port number>/Service Mapping name>/api-docs)

Service Mapping name is the name that you specify while registering your REST application in ColdFusion server.

For example, localhost:8500/test/api-docs/studentService

The swagger API document generated from the sample studentservice.cfc REST CFC file appears as shown in the

following api document:

101

Last updated 2/18/2016

"swaggerVersion":"1.2",

"apiVersion":"1.0",

"basePath":"localhost:8500/rest/test",

"resourcePath":"/studentService",

"apis":[

{

"path":"/studentService/",

"description":"",

"operations":[

{

"nickname":"addStudents",

"method":"POST",

"summary":"add students",

"type":"void",

"parameters":[

{

"name":"name",

"paramType":"body",

"allowMultiple":false,

"required":true,

"type":"array",

"items":{

"$ref":"student"

}

]

{

"nickname":"deleteStudent1",

"method":"DELETE",

"summary":"delete students",

"type":"void",

"parameters":[

{

"name":"students",

"paramType":"body",

"allowMultiple":false,

"required":true,

"type":"array",

"items":{

"$ref":"student"

}

]

{

"nickname":"addStudent",

"method":"PUT",

"summary":"add student",

"type":"void",

"parameters":[

{

"name":"name",

"paramType":"form",

"allowMultiple":false,

"required":true,

102

Last updated 2/18/2016

"type":"string"

{

"name":"age",

"paramType":"form",

"allowMultiple":false,

"required":true,

"type":"number"

}

]

}

]

{

"path":"/studentService/{name}-{age}",

"description":"",

"operations":[

{

"nickname":"getStudent",

"method":"GET",

"summary":"retrieve student",

"type":"student",

"produces":[

"application/json"

"parameters":[

{

"name":"name",

"paramType":"path",

"allowMultiple":false,

"required":true,

"type":"string"

{

"name":"age",

"paramType":"path",

"allowMultiple":false,

"required":true,

"type":"string"

}

"responseMessages":[

{

"code":404,

"message":"Not found"

{

"code":200,

"message":"Successfull",

"responseModel":"student"

}

]

}

]

{

"path":"/studentService/{studentId}",

103

Last updated 2/18/2016

"description":"",

"operations":[

{

"nickname":"updateStudentAddress",

"method":"POST",

"summary":"modify student address",

"notes":"modify the address for given studentId",

"type":"address",

"parameters":[

{

"name":"studentId",

"paramType":"path",

"allowMultiple":false,

"required":true,

"type":"number"

{

"name":"address",

"paramType":"body",

"allowMultiple":false,

"required":true,

"type":"address"

}

]

}

]

}

"models":{

"address":{

"id":"address",

"description":"this is a address component",

"required":[

"properties":{

"country":{

"type":"string"

"street":{

"type":"string"

"houseNo":{

"type":"number",

"format":"double"

"state":{

"type":"string"

}

"student":{

"id":"student",

"description":"this is a student component",

"required":[

"address",

"name",

"age"

104

Last updated 2/18/2016

"properties":{

"address":{

"$ref":"IndiaAddress"

"name":{

"type":"string"

"age":{

"type":"number",

"format":"double"

}

"IndiaAddress":{

"id":"IndiaAddress",

"description":"India address fromat",

"required":[

"properties":{

"country":{

"type":"string"

"pin":{

"type":"number",

"format":"double"

"street":{

"type":"string"

"district":{

"type":"string"

"houseNo":{

"type":"number",

"format":"double"

"state":{

"type":"string"

}

Import API from CF REST services

As a Publisher, during API creation you can import CF REST API services. Before choosing this option, ensure that

you add the CF server in API Manager.

Note: Add the CF server only when you are accessing API Manager remotely. For in-VM access, API Manager detects the

REST services automatically and loads them.API Manager can be installed over ColdFusion in your system. API Manager

is installed in cfusion/ApiManager path. For more information, refer to ColdFusion and API Manager - Integrationfeature.

105

Last updated 2/18/2016

Add CF server in API Manager

Start API Manager in Administrator mode. Click CF Discovery Server Configuration on the left pane. Add the

configuration values as shown in the sample snapshot below.

Import API

Start API Manager portal. Click Create New API and click Import REST API from ColdFusion.

CFC and Swagger mapping structure

You can compare CFC field types and Swagger field types from the following mapping structures.

Resource listing schema

The Resource Listing serves as the root document for the API description. It contains general information about the

API and an inventory of the available resources.

Swagger doc Field Name Type Description CF Fields

SwaggerVersion String Required. Specifies the Swagger

Specification version being used.

Update programmatically using

API Manager

apis Resource Object Required. Lists the resources of

the specification. The array can

have 0 or more elements

N/A

106

Last updated 2/18/2016

API declaration schema

The API declaration provides information about an API exposed on a resource. Specify only one file per resource. Save

the file in the URL described by the path field.

apiVersion string Provides the version of the

application API

Modify using application.cfc file

info Info Object Provides metadata about the API.

The clients can use this metadata,

and can be presented in the

Swagger-UI for convenience.

Modify using application.cfc file

authorizations Authorizations Object Provides information about the

authorization schemes allowed

on this API.

The type of the authorization

scheme. Values MUST be

either"basicAuth", "apiKey", or

"oauth2".

Update programmatically using

API Manager

Swagger doc Field Name Type Description CF Field

basePath string Required. The root URL serving

the API.

Add programmatically while

parsing CFC

consumes [string] A list of MIME types the APIs on

this resource can consume. The

MIME types are global to all APIs

but can be overridden on specific

API calls.

Cfcomponent.consumes

produces [string] A list of MIME types the APIs on

this resource can produce. The

MIME types are global to all APIs

but can be overridden on specific

API calls.

Cfcomponent.produces

resourcePath string The relative path to the resource,

from the basePath, which this API

Specification describes.

Cfcomponent.restpath

apis [API Object] Required. A list of the APIs

exposed on this resource. There

MUST NOT be more than one API

Object per path in the array.

Details in API Object

apiVersion string Provides the version of the

application API (not to be

confused by the (specification

version).

N/A

107

Last updated 2/18/2016

API object schema

The API Object describes one or more operations on a single path. In the apis array, there MUST be only one API

Object per path.

Operation object schema

The Operation Object describes a single operation on a path. In the operations array, there must be only one Operation

Object per method. This object includes the Data Type Fields to describe the return value of the operation. The type

field must be used to link to other models.

swaggerVersion string Required. Specifies the Swagger

Specification version being used.

N/A

authorizations Authorizations Object A list of authorizations schemes

required for the operations listed

in this API declaration.

Individual operations override

this setting. If there are multiple

authorization schemes described

here, it means they're all applied.

Add programmatically as API

Manager updates Authorization

info

models Models Object A list of the models available to

this resource. Expose the models

separately for each API

Declaration.

Generate programmatically

Swagger doc Field Name Type Description CF Field

description String A short description of the

resource.

Cffunction.description

operations [Operation Object] Required. A list of the API

operations available on this path.

The array includes zero or more

operations.

Details in Operation object

schema

Path String Required. The relative path to the

operation, from the basePath,

which this operation describes.

The value SHOULD be in a relative

(URL) path format.

Component.restpath +

Cffunction.restpath

Swagger doc Field Name Type Description CF Field

authorization Authorizations Object A list of authorizations required to

execute this operation

Programmatically from API

Manager

consumes [string] A list of MIME types this operation

can consume.

Cffunction.consumes

method String Required. The HTTP method

required to call the operation.The

value MUST be one of the

following values:

"GET", "HEAD", "POST",

"PUT","PATCH", "DELETE",

"OPTIONS". The values MUST be in

uppercase.

Cffunction. httpmethod

108

Last updated 2/18/2016

Parameter object schema

The Parameter Object describes a single parameter to be sent in an operation and maps to the parameters field in the

Operation Object. This object includes the Data Type Fields to describe the type of this parameter. The type field must

be used to link to other models.

If type is File, the consumes field must "multipart/form-data", and the paramType must be "form".

CFC/Swagger/Java types comparison

nickname String Required. A unique id for the

operation that is used by tools

reading the output for further and

easier manipulation

Cffunction.name

notes String A verbose explanation of the

operation behavior.

Cffunction.hint

parameters [Parameter Object] Required. The inputs to the

operation. If no parameters are

needed, an empty array MUST be

included.

Details in Parameter object

schema

produces [string] A list of MIME types this operation

can produce.

Cffunction.produces

responseMessages [Response Message Object] Lists the possible response

statuses that can return from the

operation.

New parameter introduced in

Cfunction

summary String A short summary of what the

operation does.

For maximum readability in the

swagger-ui, this field SHOULD be

fewer than 120 characters.

Cffunction.description

Swagger doc Field Name Type Description CF Field

allowMultiple boolean Another way to allow multiple

values for a "query", "header" or

"path" parameter.

Not available in ColdFusion.

description string Recommended. A brief

description of this parameter.

Cfargument.hint

name string Required. The unique name for

the parameter.

Cfargument.name

paramType string Required. The type of the

parameter.The value MUST be

one of these values: "path",

"query", "body","header", "form"

Note: As per spec swagger dosen’t

support "Cookie", "Matrix"

paramtype in ColdFusion

Cfargument. restargsource

required boolean A flag to note whether this

parameter is mandatory.

Cfargument.required

109

Last updated 2/18/2016

Authentication types

Overview

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:

1apiKey

2basicAuth

3OAuth2

OAuth2

In any traditional client-server application when the client requests for a protected resource or web page, the server

authenticates the client. The client passes the credentials to the server and the authentication happens. Based on the

authentication result, the client gets access to the protected resource. This approach works fine in a controlled

environment where an organization/entity manages both the client and server applications.

CFC Swagger Java Additional information

string string string

uuid string string

guid string string

query custom model coldfusion.xml.rpc.DocumentQu

eryBean

void void for argument map to "body"

numeric number(format double) Double

boolean boolean boolean

date string(format date) java.util.Calendar

any object java.lang.Object

array array of objects java.lang.Object[]

binary array of byte byte[]

struct custom model java.util.Map

xml string org.w3c.dom.Documents

110

Last updated 2/18/2016

Today’s organizations adopt an open and collaborative platform architecture in which the data is shared through an API

mechanism. The API mechanism allows any developer (internal or customers) to quickly interact with the service

without the intervention of the service owner. This framework enables users to build mashups, mobile and desktop

client applications, and other third-party services.

The services often require access to sensitive data of an API which in turn requires authentication or access control.

One common method of authentication is the user name and password authentication. However, providing password

to a third-party application has many disadvantages. Entering a password in a third-party application requires a user’s

trust. Also, from a usability perspective, it is not possible to revoke an application until the password has changed. In

the same way, the application fails to work reliably if the password has changed.

OAuth2 combats the risks mentioned above, that are associated with the password anti-pattern. 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 application receives an access token with limited lifetime access. Depending on the type of application,

obtaining an access token varies. These access tokens are called grant types. To know more about OAuth 2.0, refer to

IETF OAuth 2.0 specification.

OAuth2: Terms and actors

Resource owner

An entity capable of granting access to a protected API. A resource owner can be an end user. The resource owner

delegates authorization to the third-party client or application. Through this delegation, the application can access the

API on behalf of resource owner.

Resource Server

The server hosting the APIs. The resource server accepts and responds to protected API requests using access tokens.

The API Manager acts as resource server that validates access tokens and performs access-control on a protected API.

Client

An application that makes protected resource requests on behalf of the resource owner and the owner’s authorization.

The term "client" does not imply to any particular implementation characteristics (for example, if the application

executes on a server, a desktop, or other devices). The API Manager application is an OAuth2 client.

Authorization Server

The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining

authorization. The API Manager acts as an authorization server as well.

Access Token

Access tokens are credentials to access protected APIs. An access token is a string representing an authorization issued

to the client. The string is opaque to the client. Tokens represent specific scopes and durations of access, granted by the

resource owner, and enforced by the resource server and authorization server. The API Manager currently supports

Bearer Access tokens which are opaque tokens.

Refresh Token

Refresh tokens are credentials used to obtain access tokens. The authorization server issues the refresh tokens to the

client. The client obtains refresh tokens when the current token becomes invalid or expires.

Authorization Code

An opaque code obtained through authorization code grant flow can be redeemed to get a limited life time access token

and a refresh token. Once code is redeemed, it is no longer valid and cannot be used to get access tokens.

Scope

111

Last updated 2/18/2016

A scope is a permission associated with a protected resource. If the publisher protects any resource using OAuth2,

specifying a scope along with it requires the access token to have this scope associated with it.

Client ID

Every application with OAuth2 authorization has a unique identifier.

Client Secret

The Client Secret gets the access token in Client credentials flow and authorization code flow.

The API Manager provides complete OAuth2 support including authentication provider, role-based authorization

framework for scopes, and login web pages along with token management component. The API Manager acts as

authorization server and resource server. The authentication provider supports integration with LDAP, database, and

federated authentication using SAML.

OAuth2 endpoints

The API Manager OAuth2 provider provides the following endpoints which are used to obtain and manage access

tokens:

Authorization Endpoint

http(s)://servername:serverport/oauth2/auth: The endpoint where the end user logs in and provides the consent to

provision the authorization grant to the application.

Token Endpoint

http(s)://servername:serverport/oauth2/token: The endpoint that the client uses to obtain an access token by

presenting its authorization grant or refresh token.

Redirect Endpoint

After the user interacts with the authorization endpoint, a user is redirected back to the application. The redirect (or

callback) URL is specified in the application created in the API Manager. Currently, the API Manager does not support

multiple redirect URL’s registration in the application.

Token Info Endpoint

http(s)://servername:serverport/oauth2/tokeninfo: The tokeninfo endpoint provides information about the access

token. The response of the endpoint includes information like create time, expiry, Application Id (client_id) of the

logged in user, and scopes.

The token info endpoint receives the access token in two ways:

1. Using query parameter access_token

2. Using the authorization header

Example of a simple HTTP GET request with query parameter access _token:

http(s)://example.com/oauth2/tokeninfo?access_token=3ffb313f16856a4d6b1feecd2e50b950

(or) using the authorization header:

GET example.com/oauth2/token HTTP/1.1

Host: example.com

Authorization: Bearer 3ffb313f16856a4d6b1feecd2e50b950

Token Revocation Endpoint

112

Last updated 2/18/2016

http(s)://servername:serverport/oauth2/revoke: The endpoint that can be used to revoke any access token or refresh

token. Once revoked, the access token or refresh token becomes invalid.

OAuth2 Self Service

http(s)://servername:serverport/oauth2/self/<Logon Identifier>: If the OAuth2 server authentication provider is a

user store (LDAP or database), an end user can view the list of approved applications along with the approved scopes.

The end user can also revoke any application access. Configure the login identifier in the user store to set up this portal.

Application Registration

To obtain access tokens or authorization codes, register the application with the API Manager. The API Manager

authorization server identifies the application. Registering an application with the API manager provides the following

pair of keys:

•client Id: Client Id is a public identifier

•client secret: Client secret is a secret identifier

can access the token. To use any of OAuth2 grant types, the API Manager subscribes to at least one API that is protected

using OAuth2.

Grant types

A grant is a method of acquiring an access token that accesses an OAuth2- protected API. OAuth2 provides different

grant types for different scenarios based on the type of application (server, browser, or mobile).

Client credentials grant type

Among the four grant types of OAuth 2.0, client credentials is the simplest grant type. This grant type can be used in

cases where an application that is confidential (means ability to store client credentials safely) consumes the API.

Prerequisites

OAuth2.

Access Token Request

113

Last updated 2/18/2016

In this flow/grant type, the following request is made to the token endpoint with the following details. The HTTPs

request is made using HTTP POST with the content-type “application/x-www-form-urlencoded”.

http(s)://servername:serverport/oauth2/token

The sample below is an HTTP request to request an access token with scopes:

POST example.com/oauth2/token HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=625bc9f6-3bf6-4b6d-94ba-e97cf07a22de&client_secret=625bc123-3bf6-

4b6d-94ba-e97cf07a22de&scope=sample_read%20sample_write

Both client Id and client secret can also be sent using the authorization header. The sample HTTP request requests an

access token by passing the client credentials in authorization header along with scopes.

Authorization: Basic Base64 (clientId:clientSecret)

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=sample_read%20sample_write

Access Token Response

If the request for the access token is successful, the response is sent in JSON Format. The JSON includes the following

keys.

Request Parameter Description of the parameter

grant_type Specifies the requested grant type. To use this flow, the value is

client_credentials.

client_id The Id that uniquely identifies the application. The client id can be

found in the API Manager application.

client_secret Specifies the client credential registered with the application in API

Manager.

scope (optional) Specifies the list of scopes required for the access token. If multiple

scopes are required, specify the scopes as a space-delimited string.

Response Parameter Description of the Response Parameter

access_token The access token that can be used to call the protected API.

token_type Specifies the type of the requested access token. Currently the API

Manager supports only bearer tokens.

expires_in The lifetime in seconds of the access token. The access token lifetime

can be configured by changing the access token lifetime in API

Manager application.

scope (optional) The Granted/Approved scopes associated with the requested access

token.

114

Last updated 2/18/2016

The following example shows a JSON response:

{

"access_token": "7ee85874dde4c7235b6c3afc82e3fb",

"token_type": "bearer",

"expires_in": 1200,

"scope": " sample_read sample_write"

}

To retrieve this information any time, the client application can pass the requested access token to the token info

endpoint. As this flow involves direct client authentication, the endpoint response does not include any user info.

Access Token Revocation

Every access token has an expiry time. The access token becomes invalid and revoked automatically when the token

reaches its expiry time. When the token expires, applications request for a new token and is granted one. Client

credentials flow/grant type does not grant any refresh token. If the access token has to be revoked before its expiry time,

pass the access token to the revocation endpoint. When revoking the access token using client credentials, the flow

requires passing the client credentials in the token revocation request for a second time.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample

HTTP request shows how to revoke the Access token issued using client credentials flow.

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token&client_id=625bc9f6-3bf6-4b6d-94ba-

e97cf07a22de&client_secret=625bc123-3bf6-4b6d-94ba-e97cf07a22de

Client Secret Regeneration

You can generate the Client Secret by logging into the portal to prevent any unauthorized access to the Client Secret.

Once the Client Secret is regenerated, the older Client Secret becomes invalid. Use the new Client Secret to request for

new access tokens.

Security Considerations

The security of OAuth2 depends on the secure transmission of OAuth2 access tokens and client credentials. Therefore,

access all the OAuth2 endpoints on HTTPS (SSL/TLS) transport for production environments.

You c a n c h o o s e Mandate HTTPS in the Security Configuration page in the API Manager administrator to prevent all

OAuth2 endpoints from accepting any request over HTTP. Keep the client secret confidential and store it in a secure

database.

Keep the application private, otherwise the credentials can be captured by decompiling/analyzing the source code of

the application. Use this flow on server-side application where secure storage can be guaranteed.

How is Client Credential grant different from API Keys security?

115

Last updated 2/18/2016

In case of client credentials, you use the access token is used to call the API. On the other hand, in API Key security,

you can use the API key to validate the API. You get an extra layer of security control where you can revoke the access

token easily without modifying the client application.

Implicit/token grant type (two-legged OAuth2)

Implicit/token grant is one of the browser-based redirection flows that is suitable for pure JavaScript (client-side)-

centric or mobile applications that cannot store user credentials and does not have any server side component.

A simple example is a pure JavaScript application made using Angular/Ember and calls the API directly from JavaScript

via Ajax calls. This grant type/flow requires interaction with the end user.

Prerequisites

OAuth2. Specify the callback URL (or redirection URL) in the API Manager. After authorization request is completed,

you are redirected to this registered URL. The registered application includes the client ID that is required for this

flow/grant type.

Requesting an Access Token

The flow begins by the application by redirecting the user to API Manager OAuth2 server authorization endpoint

(/oauth2/auth) when the application tries to access an OAuth2 protected API. The URL for sending the authorization

request is shown as below:

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client

ID>&response_type=token&scope=<list of scopes delimited by string>&state=<random string>

For example,

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=token&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

116

Last updated 2/18/2016

Once the API Manager OAuth2 server receives the request, it validates all the parameters. If valid, and the

authentication method for application is user-store, you see a login page. If the authentication method for the

application is SAML SSO, you are redirected to the SAML Identity provider for authentication. After the authentication

is successful, you are presented with another page where you can provide the authorization/consent.

Here, you can select the list of scopes that are permitted for the application, which in turn is provided to the access

token.

Once it is redirected to the callback URL, the application has a script to extract the access token out of the URL

fragment. The server does not receive the access token because the URL fragment is not sent over HTTP/S by browsers.

The callback URL’s fragment contains the following parameters:

Once the access token is obtained from the grant type, it calls the protected API and gets the response from the API.

To retrieve this information any time, the client application can pass the requested access token to the token info

endpoint. The API Manager OAuth2 authorization server does not issue any refresh tokens. Once the issued access

token expires, the application goes through the OAuth2 two-legged process again.

The API Manager admin portal controls the timeout for the login credentials. If the authentication times out, provide

valid credentials (user name and password) again to log in in case of user store authentication method. In case of SAML

SSO IDP, authorization happens again. If the application is already approved, you are directly redirected to the callback

URL with the fragment having the access token and other details.

Security Considerations

Request Parameter Description of the parameter

response_type This parameter identifies this grant type flow. The value is token.

client_id This parameter uniquely identifies the application. The client id can be

found in the API Manager application.

state This parameter is an opaque pseudo-random string value used by the

client application to maintain state between the initial authorization

request and callback. The parameter prevents cross-site request

forgery. Store the scope locally when the flow starts after which can be

used later for comparison.

Scope (optional) Specifies the list of scopes required for the access token. If multiple

scopes are required, specify the scopes as a space delimited string.

URL Fragment Parameter Description of the parameter

access_token The requested access token that can be used to call the protected API.

token_type Specifies the type of the requested access token. Currently the API

Manager supports bearer tokens only so the value is Bearer.

expires_in The lifetime, in seconds, of the access token. The access token lifetime

can be configured by changing the access token lifetime in API

Manager application.

client_id Client id of the application for which the access token is issued.

state An opaque pseudo-random string value used by the client application

to maintain state between the initial authorization request and

callback. The parameter is used to prevent cross-site request forgery.

scope (optional) The granted/approved scopes associated with the requested access

token.

117

Last updated 2/18/2016

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 Access Tokens, and Client

Credentials. Therefore accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for

production environments. The API Manager administrator can mandate HTTPS transport only in the Security

Configuration page.

Also, register the HTTPs URL callback with the API Manager because the callback URL receives the access token. The

application verifies the state parameter value received in the fragment with the value stored in the initial request. Also,

verify that the client id from the URL fragment is same as the client id in the JavaScript application code.

Access Token Revocation

Every access token has an expiry time. Once it reaches the expiry time, the access token becomes invalid and is revoked

automatically. Once the access token expires, the application makes a request for the access token again. If the access

token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample

HTTP request shows how to revoke the access token:

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

Authorization code grant type (three-legged OAuth 2)

This grant type is suitable for server applications. In this flow, the access token is hidden from the end user, and instead

issues an authorization code.

Redeem the intermediary authorization code at the token endpoint with client credentials to receive access token and

refresh token. This flow also requires application to have a server component where it redeems the authorization code

for accessing the token and refreshing the token. Once the code is redeemed, it is no longer valid.

Prerequisites

118

Last updated 2/18/2016

specify a callback URL (or redirection URL) with the API Manager application so that after authorization request is

completed user is redirected to this registered URL. The registered application includes Client ID and Client Secret,

which are required for this flow/grant type.

Requesting an access token

The flow begins by the application server component redirecting the end user to API Manager OAuth2 server

authorization endpoint (/oauth2/auth). The URL for sending the authorization request is shown below:

http://<APIM_SERVERNAME>:port/oauth2/auth?client_id=<Application Client

ID>&response_type=code&scope=<list of scopes delimited by string>&state=<random string>

An example URL is:

http://example.com/oauth2/auth?client_id=9a42a56d5b5546079f2f82a62612dab9&response_type=code&

state=nkj34898sdcsd123&scope=foo_read%20foo_write

Once the API Manager OAuth2 server receives this request, it validates all the parameters. If the parameters are valid,

the user sees a login page where the user is asked to provide the login credentials (user name and password). If the

authentication method for the application is SAML SSO, the user is redirected to the SAML Identity provider for

authentication.

After the authentication is successful, you are presented with another page where you can provide the

authorization/consent. Here you can select the list of scopes that are permitted for the application, which in turn is

provided to the access token. Once scopes are selected and approved, you are redirected (to the registered URL) back

to the application. You attach a query parameter called code with its value along with the state parameter.

Now the application server component verifies the state parameter value received from the request with the value stored

in the session. If state parameter is verified, then extract the code parameter value from the request and use client

credentials to redeem this code for an access token.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=9a42a56d5b5546079f2f82a62612dab9&

client_secret=7ee85874dde4c7235b6c3afc82e3fb

Request Parameter Description of the parameter

response_type The parameter identifies the flow of the grant type. The value is code.

client_id The Client Id of the application which uniquely identifies the

application. The client id can be found in the API Manager application.

state An opaque pseudo- random string value used by the client

application to maintain state between the initial authorization request

and callback. The parameter is used to prevent cross-site request

forgery. Store the state in a server-side session for comparing it later.

scope (optional) Specifies the list of scopes required for the access token. If multiple

scopes are required, specify the scopes as a space delimited string.

119

Last updated 2/18/2016

If the given client credentials & the authorization code are valid the response will contain an access token along with a

refresh token. Refresh token is used to get a new access token when the current access token is expired/revoked. The

JSON response includes the following keys.

A sample JSON response is shown below.

{

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 1200,

"scope": "foo_read",

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

To retrieve this information any time, the client application can pass the requested access token to the token info

endpoint. Once the issued access token expires, the application can use the refresh token to get a new access token.

Refreshing access token

The example below shows how to refresh an access token using refresh token. Pass the client credentials along with the

request, either through form parameters or using basic authentication.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&scope=foo_read

JSON Key Description of the Key

access_token The requested access token which can be used to call the protected

API.

token_type Specifies the type of the requested access token. Currently API

Manager supports bearer tokens only so the value is Bearer.

expires_in The lifetime in seconds of the access token. The access token lifetime

can be configured by changing the access token lifetime in API

Manager application.

client_id Client Id of the application for which the access token is issued.

State An opaque pseudo- random string value used by the client

application to maintain state between the initial authorization request

and callback. The parameter is used to prevent cross-site request

forgery.

scope The Granted/Approved scopes associated with the requested access

token.

refresh_token Refresh token is a long-lived access token which is used to ask for a

new access token.

120

Last updated 2/18/2016

If the refresh token is expired/revoked, the application starts the three-legged dance once again. In case of user store

authentication, if the authentication times out, provide valid credentials (user name and password) again to log in. In

case of SAML SSO IDP, authorization happens again. If the application is already approved, you are redirected to the

callback URL immediately with the intermediary authorization code and state.

Access/refresh token revocation

Each issued access token has an associated expiry time. Once the expiry time is reached, the access token becomes

invalid & revoked automatically. Once the access token expires, the application gets a new access token. If the access

token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample

HTTP request revokes the access token:

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

The revoke endpoint also supports revoking the refresh token pass the refresh token in token parameter and set

token_type_hint parameter value as refresh_token.

Security considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 access tokens, and client

credentials. Therefore, accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for

production environments. The API Manager administrator can mandate HTTPS transport only in the Security

Configuration page. Also, HTTPS URL callback is registered with the API Manager application because the callback

URL receives the authorization code. The server application verifies the state parameter value received in the request

with the value stored in the session. The server application securely stores the access tokens, refresh tokens, and client

credentials in a secure database.

Resource owner/password grant type

This grant type allows the application to have their own login page. The password grant type is used in the cases where

you have complete trust on the application. This grant type is suitable for a trusted mobile application or a desktop

application. This grant type requires user interaction for requesting the access token.

Prerequisites

121

Last updated 2/18/2016

using OAuth2. The registered application includes Client ID which is required for this flow/grant type. For this grant

type to function, it is important that all subscribed APIs of type User store are configured with the same user store.

Requesting an Access Token

The user initiates the flow when accessing the installed application is presented with a login form provided by the

application. User enters the login credentials (user name, password) then the application sends an authorization request

to the API manager OAuth2 server.

In this flow/grant type, the following request is made to the token endpoint with the following details. The HTTPs

request is made using HTTP POST having the content-type “application/x-www-form-urlencoded”.

http(s)://servername:serverport/oauth2/token

POST /oauth2/token HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

grant_type=password&username=maxwell&password=sdcoio2380&client_id=

95d9c3de53a9c48e629ecb6a288f6c&scope=foo_read%20foo_write

The API Manager Server validates the incoming request and checks whether the client id is valid and is allowed to use

the password grant type. Then it checks for the application authentication method is user store or not and authenticates

the given user name and password against the user store. If the authentication is successful, the Oauth2 server validates

the scopes requested.

If the requested scopes are not empty, each scope is looked at whether granting this scope requires any group/role

membership. If user is part of the roles specified in the scope, that scope is approved. An access token with approved

scopes along with a refresh token is returned as part of the response. The JSON response includes the following keys.

Request Parameter Description of the parameter

grant_type Specifies the requested grant type. To use this flow, the value is

password.

client_id Client Id of the application which uniquely identifies the application.

The client id can be found in the API Manager application.

user name End user provided user name

password End user provided password

scope (optional) Specifies the list of scopes required for the access token. If multiple

scopes are required, specify the scopes as a space delimited string.

JSON Key Description of the Key

access_token The requested access token which can be used to call the protected

API.

token_type Specifies the type of the requested access token. Currently API

Manager supports bearer tokens only so the value is Bearer.

122

Last updated 2/18/2016

A sample JSON response is shown below:

{

"access_token": "95d9c3de53a9c48e629ecb6a288f6c",

"token_type": "bearer",

"expires_in": 2800,

"scope":"foo_read foo_write",

"refresh_token": "31cf059933238e866779a43237cd7ec"

}

To retrieve this information any time, the client application can pass the requested access token to the token info

endpoint. Once the issued access token expires, the application can use the refresh token to get a new access token.

Refreshing Access Token

The example below shows how to refresh an access token using refresh token.

POST example.com/oauth2/token HTTP/1.1

Host: server.example.com

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=31cf059933238e866779a43237cd7ec&scope=foo_read

If the refresh token is expired/revoked, the application asks you for the credentials. Restart the complete flow again.

Access/refresh token revocation

Each issued access token has an associated expiry time. Once the expiry time is reached, the access token becomes

invalid and revoked automatically. Once access token expires, the application gets a new access token. If the access

token has to be revoked before its expiry time, pass the access token to the revocation endpoint.

The access token revocation request is sent to the API Manager OAuth2 revocation endpoint. The following sample

HTTP request shows how to revoke the Access token

POST example.com/oauth2/revoke HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded

token=7ee85874dde4c7235b6c3afc82e3fb&token_type_hint=access_token

The revoke endpoint also supports revoking the refresh token pass the refresh token in token parameter and set

token_type_hint parameter value as refresh_token.

expires_in The lifetime of the access token in seconds. The access token lifetime

can be configured by changing the access token lifetime in API

Manager.

scope The granted/approved scopes associated with the requested access

token.

refresh_token Refresh token is a long-lived access token which is used to ask for a

new access token.

123

Last updated 2/18/2016

Security Considerations

The security of OAuth2 depends on the secure transmission of user credentials, OAuth2 Access Tokens, and Client

Credentials. Therefore accessing all the OAuth2 endpoints on HTTPS (SSL/TLS) transport is recommended for

production environments. The client application does not store user credentials anywhere and securely stores them. If

it is a desktop application, use a secure database. If it is an Android mobile application, store the access tokens and

refresh tokens using SharedPreferences API. If it is iOS, store the tokens in KeyChain.

Calling an OAuth2-protected API

Once an access token is obtained from any of the grant types, it can be used to call the OAuth2-protected API. The

authorization header format is:

Authorization: Bearer <OAuth2 Access Token>

Pass the access token in the Authorization Header as shown below.

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Bearer 7ee85874dde4c7235b6c3afc82e3fb

Currently, the API Manager only issues bearer tokens. The API Manager validates the access token. If the token is valid,

then the API Manager checks if the access token has the scope to call the protected API.

If both the conditions are true, then the API Manager calls the backend and gets the response and provides it to the

client.

API Key authentication

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.

When consuming an API protected using API Key, API runtime checks for the API Key in the header. If the key is not

found, then API runtime checks in the query parameters. If the key is not found, then the API runtime checks the form

(or post) parameter.

If the extracted API Key is valid, the API Manager checks whether this API Key is approved or not. If the key is

approved, the API manager gets the SLA plan for this subscription and then uses it for the rate limiting and throttling.

API Key regeneration

When an API Key is regenerated, the old Key of the application is no longer valid. The application starts using the new

key to consume the API Key.

Basic authentication

Basic authentication is the simplest form of authenticating a user by passing the user name and password in the request

when consuming an API. The API Manager allows protecting an API using the Basic authentication scheme.

124

Last updated 2/18/2016

A publisher can configure the user store to be used for the authentication. If the API resource is protected with a scope

configured with roles, then the API Manager also authorizes the role. The authorization happens during the

consumption of the API call.

Create an application in the API Manager and subscribe to an API protected using basic authentication.

With HTTP basic authentication, the user’s user name and password are concatenated, base64-encoded, and passed in

the Authorization HTTP header as follows:

Authorization: BASIC Base64 (username:password)

example: Authorization: Basic dm9yZGVsOnZvcmRlbA==

But simply passing the user name or password does not identify the application consuming the API. Send the

application unique identifier (client ID) along with the request.

An example of consuming an API protected using BASIC authentication is as follows:

GET example.com/sampleapi/v1.0/examples HTTP/1.1

Host: example.com

Authorization: Basic dm9yZGVsOnZvcmRlbA==

clientid: 3ffb313f16856a4d6b1feecd2e50b950

Once the API Manager receives a request for an API that is protected using basic authentication, it looks for the

application id. If the application id (client id) in the request is valid and approved, then the API Manager authenticates

the credentials in the request.

If authentication is successful, then the API Manager checks if the current API requested is protected with appropriate

scope and authorized role. If yes, the API Manager retrieves the user roles and checks if the current user has all the

required roles to consume this API. Once role authorization is successful, the API Manager gets the SLA plan for this

subscription for rate limiting and throttling. If rate limit is also allowed, the request is forwarded to get the response

from the application.

Adobe ColdFusion Cold Fusion 2016 API Manager En

Navigation menu

Versions of this User Manual:

Views

Navigation