28 March 2016
||Adobe ColdFusion Enterprise Edition (2016 release) (Download trial)
The administrator section of the API Manager is the place that defines how your APIs are published and consumed. You can manage all functional and non-functional information about your published APIs.
In any environment, assign administrative privileges to a select group of users. In API Manager, you can create one default administrator, after which you can further create more administrators..
You can neither delete an administrator nor remove its privileges. This is because in any installation, the API Manager has at least one administrator. The details to the default administrator is stored in the password.properties file located at <API Manager Installation Directory>/conf.
In this article, you will learn the following workflows:
- Using the API Manager to set up internal and external user stores
- Creating or importing users in the user stores
- Clustering in the API Manager
This article does not cover everything that an administrator does. For details on other settings, you should refer to the API Manager documentation. (link given at the bottom)
The discussion about the server of API Manager can be distributed in the following 3 topics
The server of the API Manger is based on the Undertow server. Hence under the General subsection of the of administrator, you will find the settings that are relevant to API Manger server and thereby relevant to the Undertow server. You can configure settings such as the address (Host, Port) of the place where API Manager will be hosted. Here you can also define the context root of your application, which in turn will determines which URLs API Manager will delegate to your web application. Similar to HTTP port, there is also an AJP port which is needed for communication between Tomcat and Apache web server.
Figure 01 : General Configuration
API Manager uses Redis as its datastore. All the data related to API hosting that it needs to store is stored in Redis. Redis was chosen due to a lot of reasons. It is extremely responsive. Real time data analysis of events is really simple. It has an in built in support for Pub/Sub.
On this page the details of the API Datastore are listed. You can use this page to migrate data from one redis node to another. For that, you need to provide the details of the other redis node. Then you also need to check the box of Perform Migration. After you confirm that you wish to migrate the data, API Manager will copy all data from your current redis node to your new node. To run API Manager from your new node, you will need to restart the server.
Figure 02 : API Datastore Configuration
API Manager uses Elasticsearch server for its analytics purposes. The settings related to that are listed on this page. Elasticsearch provides real time advanced analytics which API Manager uses for generating metrics of how the APIs are being used. Elasticsearch has a very high availability, by discovering new or failed nodes if they are set up in a clustered environment. The details for each of setting can be found on the documentation page.
Figure 03 : API Analytics Server Configuration
User stores are databases that contain information of all users who have assigned roles in any instance of API Manager. There are two types of user stores:
- Internal User Store (Portal UserStore)
- External User Store
Users from both these user stores are assigned roles in the API Manager. In Portal user stores, you can create new users giving their details, but in external user stores, you need to import already existing users to give roles to them.
The internal user store/portal user store is API Manager’s own database. The administrators have complete freedom to create any number of users. Basic details need to be filled out for the same. In case of portal user store, you can straightaway create users using the Add User button. We will cover the addition of new user later in this article.
Apart from internal user stores, there are two basic types of external user store connectors that can be used in the API Manager. They are:
- Database Table Connector
- LDAP Connector
We will walk through the setup of a user store of the LDAP Connector type. You can similarly create another user store for the Database Table Connector as well. To create an external user store, you need to go to the user store home screen. (See Fig 04). Do note that currently no external user stores exist. Clicking on the Add UserStore button takes you to the screen where you can enter the details of the user store as per the connector. (See Fig 05, 06).
Figure 04 : Existing userstores
Figure 05 : Selecting the connector type for new userstore
Figure 06 : Add user store form
After entering all the details in the form, clicking on Save takes you to the User store home page, where you can see the newly added user store listed. (See Fig 07)
Figure 07 : List of existing user stores
There are two types of users in the API Manager. The users depend on the type of user stores they belong to (Internal/External).
You need to import users from external data stores first and then assign the roles to the users. The two ways you create create users in the API Manager are:
- Adding a user
- Importing a user
Adding a User
Figure 08 : Users Home Page.
Click Add User to add the details of a new user.(See Fig 08).
Figure 09 : Add user screen.
The Roles check-boxes defines how a new user can access the system. For example, if you create a user with the roles Publisher and Subscriber, to the user cannot log in to the API Manager administrator using the credentials.
After you successfully add the user, you are redirected to the Users Home page again. (See Fig 10) You can also view the list of users present by default on the page. If the list is too long, you can also filter the list of users by name and/or roles.
Figure 10 : Successful addition of the user
A second way to create users in the API Manager is to import them from an external user store. Set up an external user store prior to importing the users. Click Import External User on the users’ home page.
You are redirected to a page where you can select any external user store and search for the users that exist in that user store. From the list, you can import one or more users.
- If the external user does not have an email associated with them, you must enter a valid email id.
- Select at least one role before importing the users. (See Fig 11)
Figure 11 : Succesfully importing external user
To further confirm that the user preethi is imported, you can go back to the users home page and search for the user after selecting the user store it belongs to externally. (See Fig 12)
Figure 12 : Figure showing imported user
To achieve high scalability and performance, offset up clusters in the API Manager, where multiple number of nodes work in tandem with each other. A cluster of two or more API Manager nodes can contain a single running instance of API Datastore and API Analytics Server. Additionally the API Datastore and API Analytics Server can also have a clustered setup of their own.
The cluster of API Manager is homogenous in nature, which means, any change in one node of API Manager instantly reflects in all the other nodes. For example, If a publisher publishes their API from one node, the API is visible to all the other nodes of the API Manager.
This homogeneity is achieved through Publisher-Subscriber (Pub-Sub) service written to notify all the nodes about any changes done. These changes include all the administrator level settings. This means, if a new SLA plan is added at a node, it is available to all the other nodes as well.
The nodes can be in a web server, which can act as load balancer for the cluster.
From the Cluster page in administrator, you can enable/disable the cluster of your API Manager setup. To make these changes effective, restart the API Manager.
Figure 13 : Clustering in API Manager
API Manager uses Service Level Agreement (SLA) to formally define the way APIs can be used.
On the top of the SLA settings page, you can see the options to choose a Rate Limit Algorithm. This option defines the type of algorithm to be used to limit the rate at which API is consumed namely, Rolling Window and Fixed Window.
In fixed window algorithm, a period is considered from start of the time unit to the end of the time unit. For example, an API call made at 59th minute is considered a part of the time period of 1st hour and another API call made at 62nd minute is considered part of the net hour, even though they are 3 minutes apart, they are considered part different time units.
In rolling window algorithm, a period is considered from the instant of time at which (every) request is made to the end of the time unit. If we consider the previous example, then calls made at 59th and 63rd minute will be considered to be in the same time unit. This essentially smoothens out the possible spikes in the API request rates with respect time.
Each SLA is defined by several parameters. Rate Limit defines how fast an API can be accessed at an order of time second/minute/hour. Throttle Limit defines how far an API can be accessed, i.e., how many requests should the API Manager entertain at bigger order of time such as day/week/month. Now the Throttle Limit can be soft or hard. Setting it hard means the number of API requests cannot exceed this limit. Setting it to soft gives you two extra settings namely, Notify Limit and Exceed Limit. Notify limit is the percentage of usage at which notification will be sent to the user. Exceed Limit is the percentage by which usage will be allowed to exceed the limit prescribed.
Figure 14 : SLA home page
This article covers only a part of all the things that you can perform with the API Manger Administrator. For more details on other administrator features, refer to the API Manager Administrator Documentation.