Managing Contracts for your API

Manage contracts for apps that are connected to your API.

Table of Contents

1. How do I see the status of my API's contracts with apps?
2. How do I revise a contract?
3. How do I export a specific contract for my API?
4. What are the contents of the API contract export file?
5. Why is there a separate Activate step for production contracts?

How do I see the status of my API's contracts with apps?

You can review the status of your API's connections, including pending and active API access requests, in the My APIs > API > Apps page. This page provides a high level summary of workflow status for apps with current API access contracts or pending API access requests for the current API.

Each listing includes:

• Apps—The App Name. This link clicks through to the App Details page.
• Legals—A column that indicates whether the Legal Agreements have been accepted (Check = Accepted, No Check = No Accepted).
• Sandbox / Production—Represent the two environments that an API Access Request can be submitted for. Each column displays the current status of the API Access Request and available API management functions (for example, Cancel, Suspend, Resume). The valid actions for a specific contract are determined by the current state of the contract; for example, only a contract that is currently in a state of Suspended can be resumed, and only a contract in a state of Activated can be cancelled. For more information on API access states and valid actions, see What is the default workflow for API contracts?

The following tables provide explanations for information you might see on this page.

Contract Status	Description
Access Requested	An App has requested access to an API but the request has not been approved and activated in the Sandbox or Production environment.
Approved	A contract in the production environment has been approved but not yet activated.
Active	API Access has been approved and activated.
Inactive	API access has not yet been requested.
Rejected	The API Access Request has been rejected.
Suspended	API Access that was previously active has been suspended.

 

App Management Task	Description
Cancel	Cancels an API Access Request. Listing is removed from the API Connections page. Requestor must submit another request to initiate the process again.
Suspend	Suspends the API Access Request. This action can only be performed when the request status is Active.
Resume	Resumes the API Access Request and changes the request status to Active after it has been suspended.

 

API Access Request Task	Description
Approve	Approves the API Access Request. In the sandbox environment, a contract that's in an Approved state is fully available for testing. In the production environment, a contract in an Approved state must be activated before the app can use it at runtime or in Test Client.
Reject	Rejects the API Access Request.
Cancel	Cancels the API Access Request. The app developer must submit another request to initiate the process again.
Activate	Activate a contract in the production environment. The contract must already be in an Approved state. Once a contract has been activated, the app can use it in the production environment.
Suspend	Suspends the API Access Request and is performed after the request has been activated.
Resume	Resumes the API Access Request and puts it into an activated state after it has been suspended.

Back to top

How do I revise a contract?

When a contract that an app has with your API is approved and/or activated, you can still revise the contract to modify the licenses or make other changes as needed.

When you revise an active contract, the platform creates a new contract based on the existing one. You can then modify the properties as needed. When the new contract is activated, the original version is automatically cancelled, and the new contract becomes the active contract. There is no interruption of traffic for the contract, and the metrics for the contract continue to increment.

To revise a contract:

1. Navigate to My APIs, choose the API, and then, in the left navigation, click Apps.
2. Locate the contract on the list.
3. To the right of the entry, click the icon to view the list of options for the contract, and choose Revise.
4. Revise the contract as needed.
5. Save changes.

Back to top

How do I export a specific contract for my API?

You can export all the API contracts for your API when you export the API via the Export button on the API Details page (see How do I export an API?).

However, you might want to export a specific contract. You can do that via the My APIs > API > Apps page, where you can view the contracts for all apps that are connected to your API.

To export an individual contract for an API:

1. Navigate to My APIs, choose the API, and then, in the left navigation, click Apps.
2. Locate the contract on the list.
3. To the right of the entry, click the icon to view the list of options for the contract, and choose Export.
4. On the Export overlay, check the boxes to include the following in the export file:
   • API
   • Application
   • License
   • Policies
5. Click Export.
6. Choose to save or open the export file (apicontract-export.zip).

Back to top

What are the contents of the API contract export file?

The API contract export file includes all the core information about the API/app contract, as well as any of the optional additional information you specified.

The export file will generally include the following:

• Files at root level:
  • objectgraph.xml: An XML file that shows the relationships between resources.
  • objectdata.xml: An XML-based summary of all the data in the export file.
  • exportproperties.properties: a properties file showing which options were included in the export file.
• bpels: a folder containing XML business process files (bpel files). One for each operation, for each environment. So, for example, if the API has five operations, and runs in Sandbox and Production environments, there are 10 bpel files.
• services: a folder containing a subfolder for each environment, each subfolder containing a bpel.xml file for the applicable service/environment.
• wsdls: a folder containing WSDL files for the service.

Back to top

Why is there a separate Activate step for production contracts?

The lifecycle of a contract between an app and an API is controlled by several factors.

The first factor is the API definition (Tab 3, Proxy), where you can determine whether contract requests are auto-approved or require manual approval. This setting is specific to each API environment. If auto-approval is set to Yes, when the app developer requests a contract it is approved immediately. Results depend on the environment:

• Sandbox: Auto-approval means that the app developer can use it right away, and the endpoint is available in Test Client for testing.
• Production: When the contract is manually approved or auto-approved, there is an extra step, Activate, that must be completed before the app can access the API in the production environment. If auto-approval is turned off, the API Admin must first approve the request, at which point the contract status changes from Pending to Approved; and must then activate. If auto-approval is turned on, the API Admin must activate, at which point the status changes from Approved to Activated.

The contract must be in an Activated state before it can be used at runtime. Network Director rejects the request if the contract is in an Approved state.

The Approve and Activate actions can be performed by the API Admin or the Business Admin.

So, why is there a separate activation step for production contracts?

Essentially, the Approved state indicates approval from the business side. The Activated state indicates that all is ready from the operations side.

By default, the API Admin (or Business Admin) performs both actions. However, making it into two actions:

• Adds an extra layer of approval before production access is granted.
• Adds flexibility, opening the door to possible customization.

The approval process can be customized by implementing a custom workflow. For example, a custom workflow could be implemented that would not allow all API admins to activate contracts, but rather would limit those rights to a subset of API Admins who have an additional role.

Back to top