In API Manager, a contract represents an agreement permitting a specific consumer version to use a specific service version. Consumer owners request contracts and service owners approve or deny them. A service owner can establish pre-defined SLA tiers that consumers can view and select from to generate a contract request. If no SLA tiers are defined for a service version, a consumer owner can request a contract without an SLA tier.
- Contract Relationships
- Contract Management for the Service Owner
- Advantages of Contract Management
- Defining SLAs
- Applying Policies to Enforce Contracts
- Providing Documentation
- Approving or Rejecting Contract Requests
- Supporting Consumer Key Lookup
Mule 3.4.1, 3.4.2
CloudHub Mule Runtime (December 2013)
- Contract Management for the Consumer Owner
- Go Further
Note that a single consumer version cannot have a contract with more than one version of the same service at the same time. If a consumer version already has an active contract with a service, API Manager prohibits an additional contract between that same consumer version and any version of that same service. However, a single service version may have active contracts with multiple versions of the same consumer.
For example, if each colored line below represents a contract, these diagrams illustrate the limitations on what contract structures are allowed.
Once a contract is approved, API Manager generates a unique contract key. A consumer application can include this contract key in service calls or, if the consumer is performing a dynamic lookup using the , API Manager verifies the contract automatically when resolving the service call. The Mule agent reads the contract key and queries API Manager at runtime for the appropriate rate limiting or throttling policy to apply according to the consumer's contracted SLA, if any.
Contracts are also required to support a dynamic lookup by consumer key, the unique identifier for each consumer version registered. Read more about supporting consumer key lookups.
Earlier versions of the API Manager agent do not support consumer key lookups. Consult the agent compatibility guide and associated release notes for clarification.
Either the service owner or the consumer owner (or any administrator/organization owner) can revoke the contract at any time.
Contract Management for the Service Owner
As a service owner, you define whether or not to require contracts for consumers to access your service. Even without contracts, you can apply runtime governance policies to your service. For example, you can set up HTTP basic authentication so that all consumers must authenticate before being allowed to access the service; you can also apply a throttling or rate limiting policy to limit all incoming requests, regardless of the source, to a certain amount per time period.
Advantages of Contract Management
If you are interested in fine-tuning access levels or other policies to affect certain groups of consumers, contracts become necessary. With this requirement comes several advantages:
- Requiring contracts limits access to the service to registered consumers in API Manager, giving you visibility into what consumers are using your service for.
- Setting up SLA tiers and enforcing them via SLA-based contracts allows you to pre-define usage levels for different groups of consumers so that your server throughput is more predictable.
- Always having access to contact details for the other party in a consumer-provider contract facilitates a clear line of communication between consumers and providers when either party needs to upgrade an application to a new version.
To set up and manage contracts in API Manager, a service owner typically completes the following steps:
- Define one or more SLAs (optional)
- Apply two policies:
- a contract enforcement policy
- a contract-based rate limiting or throttling policy (required if you want to enforce SLA tiers)
- Provide documentation for end users
- Approve or reject contract requests
Alternatively, if you want to support service calls that use the consumer key lookup type instead of requiring consumer applications to include the contract ID in the service call, you should not apply a contract enforcement policy. See Supporting Consumer Key Lookup below for more information about this use case.
In API Manager, contracts can be based on SLA tiers set by the service owner. However, this is optional. It is possible to create a contract without any SLA tiers. In that case, the contract exists merely to allow the consumer to use the service rather than to limit the consumer to a specific SLA tier.
To define an SLA tier for a service, you must be the service owner or an administrator. Complete the following procedure to define an SLA tier:
- On the service's main screen, click the SLA Tiers tab (see image below).
- Click Add SLA Tier to define a new tier.
- Name your tier, then enter a brief Description, which appears immediately next to the tier name to help end users determine which tier might be appropriate.
- Define the throughput by filling in the maximum number of requests per time period that you want to allow on this tier. You can set the time period to millisecond, second, minute, hour, or day.
- Click Create SLA Tier to save your tier.
Repeat these steps to define as many additional tiers as you like. Note that the most recently created tier appears at the bottom of the list.
Applying Policies to Enforce Contracts
Next, a service owner or an administrator must add policies to ensure that contracts are enforced. For more information about creating and applying policies, refer to Runtime Policy Management.
Apply a contract enforcement policy to ensure that all incoming service calls include a valid contract key. API Manager sets the contract key expression with the policy, so be sure to communicate the format of the expression in your release notes so that end users of your service know how to format service calls.
If your service has SLA tiers defined, you will also need to apply either a contract-based rate limiting policy or a contract-based throttling policy. In API Manager, throttling policies queue any requests that exceed the threshold for later processing; rate limiting policies reject any requests that exceed the threshold. Apply one of these two policies to your service version or endpoint.
When only a contract enforcement policy is applied, all incoming services need to include a valid contract key. When either a contract-based rate limiting or contract-based throttling policy is also applied, API Manager reads the contract key, looks up the corresponding SLA upon which that contract was based, and enforces the rate-limiting or throttling policy according to the SLA tier.
All other users, unless they are a service owner or an administrator, cannot view details about the policies you have applied to your service; other users can only see the policy characteristics applied to a service. (See details about characteristics in the summary table of policy templates.)
However, in the case of some policies, users need additional details about the requirements to satisfy the policy. Such users rely on the service description, release notes, and any supporting documentation for instructions to properly format a service call to comply with any runtime policies.
As a final step of service setup, a service owner should document the following details:
- any contract requirements
- the specific contract key expression expected by the inbound endpoint
- any other information that an end user needs to properly configure a service call
Depending on your preference, you can can include this documentation directly in the service description, in the service version release notes, or on your API's customized developer portal homepage, which you can link to from the description. You can also attach an artifact to your service version containing this information.
Approving or Rejecting Contract Requests
Once consumer owners submit contract requests, you will need to approve or reject them. API Manager will send you an automated email to notify you that a consumer owner has requested a contract. To review the request and approve or reject it, click the Contracts icon in the top navigation bar. Note that you can set the filter on the left side of the page to "Pending Approval" to view just the contract requests requiring your attention, if you wish. Approve or reject the requests by clicking the icons on the right of the screen.
Supporting Consumer Key Lookup
Mule 3.4.1, 3.4.2
CloudHub Mule Runtime (December 2013)
This section provides alternate instructions for service owners interested in supporting consumer key lookups against their services.
A consumer key lookup is a type of service virtualization that allows consumer applications to perform lookups using the unique consumer key of a consumer version and the serviceId of the service. This type of lookup includes neither the service version number nor the contract ID (contract key) in the consumer application's code, thus facilitating smooth transitions to new service versions without any adjustments to the consumer applications. In this use case, if you wish to enforce compliance, apply a Contract Enforcement - Consumer Key-Based policy (available with API Manager agent version 5.0.0 or later) instead of a Contract Enforcement - Contract Key-Based policy to the target endpoints.
To make this use case work, the service owner should proceed as follows:
- If you wish to enforce compliance, apply a Contract Enforcement - Consumer Key-Based policy.
- Define one or more SLAs (optional).
- If you have defined SLAs, apply either a throttling or rate-limiting policy. Apply the contract-based version if you are enforcing compliance using a Contract Enforcement - Consumer Key-Based policy.
- Provide documentation that asks consumer owners to request contracts against your service.
- Approve contracts.
When you register a new version of your service, follow these steps to migrate consumers seamlessly to the new version:
- Go to API Manager to find all contracts currently active for your existing service version.
- Contact the consumer owners of those consumers to advise them of the new version.
- Have the consumer owners delete their existing contracts and request new contracts with the new version.
- Approve those new contracts.
As soon as the new contracts are approved, the consumer's service calls continue as before without any changes in the code of the consumer applications. API Manager reads the same consumer key and serviceId in the service call, looks for a matching contract, and uses the contract information to route the call to the appropriate service version.
Contract Management for the Consumer Owner
This section focuses on contracts from the perspective of the consumer.
In order to consume a service that requires a contract, a consumer must be registered in the repository. The user who registers the consumer in the repository becomes the consumer owner. Additional users can be added as consumer owners after the consumer is registered. Only a consumer owner may request contracts with services for that consumer. The following steps outline the procedure to request a contract:
- Navigate to the service's main screen.
- Select the appropriate version of the service.
Click Request Contract.What if this button is not clickable?
If the Request Contract button is inaccessible, this indicates that the service is not actively available for contracts. Check to make sure the service version is marked as "active." If it is inactive, new contracts cannot be requested.
Select the Consumer for which you want the contract. The list includes only the consumers for which you are the consumer owner.What if no consumers are listed?
If you see "No consumers found" in the consumers drop-down, you are not the consumer owner of any consumers in API Manager. You must first register your consumer or be added as a consumer owner of an already registered consumer before you can request contracts.
- Select the consumer Version.
- Select the desired SLA Tier. Note that if this option is not shown, then no SLA tiers are defined for that service version.
- Click Request Contract.
The service owner(s) receives an email alert that your contract has been requested. A service owner must approve the contract request before a contract key is generated. When your contract is approved, you receive an email notifying you of the approval and supplying the contract key.
The contract key is also visible to you in API Manager in two locations:
- on the Contracts page, accessible via the Contracts icon on the top navigation bar. Go here to review the status of all your contract requests.
- on the Services Consumed tab on your consumer's main page (see image below).
Note that all users other than the consumer owner (or an administrator) cannot view the contract key. For other users, this tab displays information about the services the consumer is contracted to consume, but the contract key is not visible (see image below).
If you are both the consumer owner and the service owner (or if you have an administrator account), you can also see the contract key on the service's main screen on the Consumers tab (see image below).
If you are not the service owner or an administrator, this tab displays information about consumers which are contracted to consume this service version, but the contract key is not visible (see image below).
You can now use your contract key in your service calls. Refer to any specific instructions provided by the service owner – in the description on the service's main screen, in the release notes, or in any attached artifacts – to format your service calls. If the service owner has provided no specific documentation, check the developer guide for help with formatting service calls.
Note that if the service you are calling specifies that it supports consumer key lookup, you may want to read the alternate instructions, above, that describe this use case.
As the consumer owner, you can refer to the Services Consumed tab on your consumer's main screen to view contract keys for all consumer-provider contracts that are active for your consumer. From this screen, you can delete a contract at any time by clicking the Revoke icon . The service owner can also revoke the contract from Consumers tab on the service's main screen.