Apiman Concepts

The top level container concept within the API management project its called the organization. All other entities are managed within the scope of an organization.

When users log into the API management system they must be affiliated with one or more organization. Users can have different roles within that organization allowing them to perform different actions and manage different entities. Please see the 'User Management' section below for more details on this topic.

What an organization actually represents will depend upon who is using API management. When installed within a large enterprise, an organization may represent an internal group within IT (for example the HR group). If installed in the cloud, an organization might represent an external company or organization.

In any case, an organization is required before the end user can create or consume APIs.

The most important concept in API management is the policy. The policy is the unit of work executed at runtime in order to implement API governance. All other entities within the API Manager exist in support of configuring policies and sensibly applying them at runtime.

When a request for an API is made at runtime, a policy chain is created and applied to the inbound request, prior to proxying that request to the back-end API implementation. This policy chain consists of policies configured in the API Manager.

An individual policy consists of a type (e.g. authentication or rate limiting) as well as configuration details specific to the type and instance of that policy. Multiple policies can be configured per API resulting in a policy chain that is applied at runtime.

It is very important to understand that policies can be configured at three different levels within API management. Policies can be configured on an API, on a plan, or on a client app. For more details please see the sections below.

A plan is a set of policies that define a level of service for an API. When an API is consumed it may be consumed through a plan. Please see the section on 'API Contracts' for more information.

An organization can have multiple plans associated with it. Typically each plan within an organization consists of the same set of policies but with different configuration details. For example, an organization might have a Gold plan with a rate limiting policy that restricts consumers to 1000 requests per day. The same organization may then have a Silver plan which is also configured with a rate limiting policy, but which restricts consumers to 500 requests per day.

Once a plan has been fully configured (all desired policies added and configured) it must be locked so that it can be used by APIs. This is done so that API providers can’t change the details of the plan out from underneath the client app developers who are using it.

An API represents an external API that is being governed by the API management system. An API consists of a set of metadata including name and description as well as an external endpoint defining the API implementation. The external API implementation endpoint includes:

In addition, policies can be configured on an API. Typically, the policies applied to APIs are things like authentication, or caching. Any policies configured on API will be applied at runtime regardless of the client app and API contract. This is why authentication is a common policy to configure at the API level.

APIs may be offered through one or more plans configured in the same organization. When plans are used, API consumers (client apps) must consume the API through one of those plans. Please see the section on 'API Contracts' for more information. Alternatively, an API can simply be marked as "Public", in which case any client may access the API’s managed endpoint without providing an API Key.

Only once an API is fully configured, including its policies, implementation, and plans can it be published to the Gateway for consumption by client apps. Once an API has been published, it can only be changed if it is a "Public" API. APIs that are offered via Plans are immutable - to change them you must create a new version. The reason for this is that API consumers may have created Contracts with your API, through your Plan. When they do this, they must agree to some terms and conditions. It is therefore understood that the terms to which they are agreeing will not change. However, for Public APIs, there is no such agreement. For this reason, you can make changes to Public APIs and re-publish them at any time.

A client app represents a consumer of an API. Typical API consumers are things like mobile applications and B2B applications. Regardless of the actual implementation, a client app must be added to the API management system so that Contracts can be created between it and the APIs it wishes to consume.

A client app consists of basic metadata such as name and description. Policies can also be configured on a client app, but are optional.

Finally, API Contracts can be created between a client app and the API(s) it wishes to consume. Once the API Contracts are created, the client app can be registered with the runtime gateway. Policies and Contracts can be added/removed at any time. However, after any changes are made, you must re-register the client app.

An API contract is simply a link between a Client App and an API through a plan offered by that API. This is the only way that a client app can consume an API. If there are no client apps that have created API contracts with an API, that API cannot be accessed through the API management runtime gateway (unless of course the API is "Public").

When an API Contract is created, the system generates a unique API key specific to that contract. All requests made to the API by a Client App through the API Gateway must include this API key. The API key is used to create the runtime policy chain from the policies configured on the API, plan, and client app.

API Contracts can only be created between Client Apps and published APIs which are offered through at least one Plan. An API Contract cannot be created between a Client App and a Public API.

A policy chain is an ordered sequence of policies that are applied when a request is made for an API through the API Gateway. The order that policies are applied is important and is as follows:

Within these individual sections, the end user can specify the order of the policies.

When a request for an API is received by the API Gateway the policy chain is applied to the request in the order listed above. If none of the policies fail, the API Gateway will proxy the request to the backend API implementation. Once a response is received from the back end API implementation, the policy chain is then applied in reverse order to that response. This allows each policy to be applied twice, once to the inbound request and then again to the outbound response.

Users must self register with the management UI in order to be given access to an organization or to create their own organization. In some configurations it is possible that user self registration is unavailable and instead user information is provided by a standard source of identity such as LDAP. In either case, the actions a user can take are determined by that user’s role memberships within the context of an organization.

Users can be members of organizations. All memberships in an organization include the specific roles the user is granted. It is typically up to the owner of an organization to grant role memberships to the members of that organization.

Roles determine the capabilities granted a user within the context of the organization. The roles themselves and the capabilities that those roles grant are configured by system administrators. For example, administrators would typically configure the following roles:

Each of these roles is configured by an administrator to provide a specific set of permissions allowing the user to perform relevant actions appropriate to that role. For example the Client App Developer role would grant an end user the ability to manage client apps and API contracts for those client apps. However that user would not be able to create or manage the organization’s APIs or plans.

Plans can be created easily from the 'Plans' tab of the organization details page. Simply click the 'New Plan' button and then provide a plan name, version, and description. Once that information is provided, click the 'Create Plan' button. If successfully created, you’ll be taken to the plan details page.

If you switch to the 'Policies' tab on the plan details page you can configure the list of policies for the plan. Please note that the order of the policies can be changed and is important. The order that the policies appear in the user interface determines the order they will be applied at runtime. You can drag a policy up and down the list to change the order.

To add a policy to the plan click the 'Add Policy' button. On the resulting page choose the type of policy you wish to create and then configure the details for that policy. Once you have configured the details click the 'Add Policy' button to add the policy to the plan.

Once all your plan policies are added and configured the way you want them, you will need to Lock the plan. This can be done from any tab of the Plan UI page. Locking the plan will prevent all future policy changes, and make the plan available for use by APIs.

First the user must create an API within an organization. If an organization does not yet exist one can easily be created. See the 'Managing Organizations' section for details.

From the organization details page, navigate to the 'APIs' tab and click on the 'New API' button. You will be asked to provide an API name, version number, and description.

If successfully created, you will be taken to the API details page. From here you can configure the details of the API.

Every API must be configured with an API implementation. The implementation indicates the external API that the API Gateway will proxy to if all the policies are successfully applied. Click the 'Implementation' tab to configure the API endpoint and API type details on your API.

The 'Implementation' tab is primarily used to configure the details of the back-end API that Apiman will proxy to at runtime. You must configure the following:

Additionally, the 'Implementation' tab allows you to configure any security options that might be required when proxying requests to the back-end API. For example, if you are using two-way SSL to ensure full security between the API Gateway and your back-end API, you may configure that here. We also support simple BASIC authentication between the gateway and your back end API. Please note that BASIC authentication is not ideal, and especially insecure if not using SSL/HTTPS to connect to the back end API.

If the Apiman administrator has configured multiple Gateways (see the "System Administration / Gateways" section below), then the 'Implementation' tab will also include an option that will let you choose which Gateway(s) to use when publishing. You may select one or more Gateway in this case. If you choose multiple Gateways, then when you click the 'Publish' button, Apiman will publish the API to all the selected Gateways.

Do not forget to click the Save button when you are done making changes.

As a provider of an API, it is best to include as much information about the API as possible, so that consumers can not only create contracts, but also learn how to make calls. For this purpose, you can optionally include an API Definition document by adding it to your API on the Definition tab. Currently the only supported type of definition file is Swagger. Include a swagger spec document here so that consumers of your API can browse information about your API directly in the API Manager UI.

Before an API can be consumed by a client app, it must make itself available through at least one of the organization’s plans (or it must be marked as "Public"). Marking an API as public or making an API available through one or more plan can be done by navigating to the 'Plans' tab on the API details page. The 'Plans' tab will list all of the available plans defined by the organization. Simply choose one or more plan from this list. If no plans are needed, you can instead mark the API as "Public", making it available to be consumed anonymously by any client. Although an API can be both Public and available through one or more plan, it is unusual to do so.

API policies can be added and configured by navigating to the 'Policies' tab on the API details page. The 'Policies' tab presents a list of all the policies configured for this API. To add another policy to the API click the 'Add Policy' button. On the resulting page choose the type of policy you wish to create and then configure the details for that policy. Once you have configured the details click the 'Add Policy' button to add the policy to the API.

After all of the configuration is complete for an API, it is time to publish the API to the runtime gateway. This can be done from any tab on the API details page by clicking the 'Publish' button in the top section of the UI. If successful, the status of the API will change to "Published" and the 'Publish' button will disappear.

Once the API has been published, it may or may not be editable depending on whether it is a "Public" API or not. For "Public" APIs, you will be able to continue making changes. After at least one change is made, you will have the option to "Re-Publish" the API to the Gateway. Doing so will update all information about the API in the Gateway. However, if the API is not Public, then the API will be immutable - therefore in order to make any changes you will need to create a new version of the API.

Once an API is published and is being consumed at runtime, metrics information about that usage is recorded in a metrics storage system. See the Metrics section of the API Gateway documentation for more about how and when metrics data is recorded.

If an API has been used by at least once, then it will have metrics information available. This information can be viewed in the 'Metrics' tab on the API’s details page. On this page you can choose the type of metric you wish to see (e.g. Usage metrics and Response Type metrics) as well as a pre-defined time range (e.g. Last 30 Days, Last Week, etc…​).

The API Metrics page is a great way to figure out how often your API is used, and in what ways.

As an alternative to manually creating and configuring an API, Apiman also supports importing an API from a globally configured API Catalog.

An API can be imported into Apiman in one of two ways. First, from the Organization’s "APIs" tab you can click the down-arrow next to the "New API" button and choose the "Import API(s)" option. This results in a wizard that will guide you through importing one or more API from the catalog into the Organization. This wizard will allow you to search for, find, and select multiple APIs. It will then walk you through choosing your Plans or making the APIs "Public". Once all the wizard pages are completed, you can then import the API(s).

Another option for importing an API from the catalog is to use the API Catalog Browser UI, which can be found by clicking the "Browse available/importable APIs" link on the API Manager Dashboard. This link will open the catalog browser, allowing you to search for APIs to import. The catalog browser is a friendlier interface, but only allows you to import a single API at a time.

If you have marked an API as "Public", then consuming it is a simple matter of sending a request to the appropriate API Gateway endpoint. The managed API endpoint may vary depending on the Gateway being used, but it typically of the following form:

Simply send requests to the managed API endpoint, and do not include an API Key.

In order to consume an API that is not "Public" you must first create a client app. Client Apps must exist within the context of an organization. If an organization does not yet exist for this purpose, simply create a new organization. See the section above on 'Managing Organizations' for more information.

To create a new Client App click the 'Create a New Client App' link on the dashboard page. On the resulting page provide a client app name, version, and description and then click the 'Create Client App' button. If the client app is successfully created, you will be taken to the client app details page.

The primary action taken when configuring a client app is the creation of Contracts to APIs. This is what we mean when we say "consuming an API". There are a number of ways to create API contracts. This section will describe the most useful of these options.

From the Client App details page, you can find an API to consume by clicking on the 'Search for APIs to consume' link in the top section of the page. You will be taken to a page that will help you search for and find the API you wish to consume.

Use the controls on this page to search for an API. Once you have found the API you are interested in, click on its name in the search results area. This will take you to the API details page for API consumers. The consumer-oriented API details page presents you with all of the information necessary to make a decision about how to consume the API. It includes a list of all the API versions and a list of all of the available plans the API can be consumed through.

Note that you can click on an individual plan to see the details of the policies that will be enforced should that plan be chosen. Click on the 'Create Contract' button next to the plan you wish to use when consuming this API. You will be taken to the new contract page to confirm that you want to create an API contract to this API through the selected plan. If you are sure this is the API contract you wish to create, click the 'Create Contract' button and then agree to the terms and conditions. If successful, you will be taken to the 'Contracts' tab on the client app details page.

From the 'Contracts' tab on the client app details page you can see the list of API contracts already created for this client app. It is also possible to break API contracts from this same list by clicking an appropriate 'Break Contract' button.

If An API provider has included An API Definition for the API they are providing, you will be presented with an additional link on the consumer-oriented API details page labeled "API Definition". This link will take you to a page where you can browse the detailed documentation for the API. The detailed documentation should be very helpful in learning what resources and operations are supported by the API, which will aid in figuring out how precisely to consume the API.

Just like plans and APIs, client apps can have configured policies. The 'Policies' tab will present a list of all the policies configured for this client app. To add another policy to the client app click the 'Add Policy' button. On the resulting page choose the type of policy you wish to create and then configure the details for that policy. Once you have configured the details click the 'Add Policy' button to add the policy to the client app.

Of course, just like for Plans and APIs, you can manage the Client App policies from the 'Policies' tab. This allows you to not only add new policies but also edit, remove, and reorder them.

After at least one API contract has been created for the client app, it is possible to register the client app with the runtime gateway. Until the client app is registered with the runtime gateway, it is not possible to make requests to back-end APIs on behalf of that client app.

To register the client app with the gateway, simply click the "Register" button at the top of the Client App details UI page (any tab). If the status of the client app is "Ready", then the 'Register' button should be enabled. If successful, the client app status will change to "Registered", and the 'Register' button will disappear.

Once the client app is registered, you can continue to make changes to it (such as modify its policies or create/break API Contracts). If you do make any changes, then the 'Re-Register' button will become enabled. Whenever you make changes to your Client App, you must Re-Register it before those changes will show up in the Gateway.

After a client app has been registered with the runtime gateway, it is possible to send requests to the back-end APIs on behalf of that client app (through the client app’s API contracts). To do this you must know the URL of the managed API. This URL 'optionally' includes the API Key generated for the Client App.

To view a list of all of these managed endpoints, navigate to the 'APIs' tab on the API detail page. Each API contract is represented in the list of managed endpoints. You can expand an entry in the managed API endpoints table by clicking the '>' icon in the first column. The resulting details will help you figure out the appropriate endpoint to use for a particular managed API.