Managing Contracts for your API

Manage contracts for apps that are connected to your API.

Table of Contents

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 APIs > My APIs > choose 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's Details page.
  • Legals—A column that indicates whether the Legal Agreements have been accepted (Check = Accepted, No Check = No Accepted).
  • Sandbox / Live —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 Live implementation.
Approved A contract in the Live implementation 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 Apps page for the API. 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 implementation, a contract that's in an Approved state is fully available for testing. In the Live implementation, 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 Live implementation. The contract must already be in an Approved state. Once a contract has been activated, the app can use it in the Live implementation.
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.

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. Go to APIs > My APIs > choose API > 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.

How do I suspend an app's access to my API?

You can temporarily suspend an app's access to your API. You can resume access later by clicking Resume.

Note: Suspend and Resume actions are available only to the API Admin; the app developer cannot suspend/resume a contract.

To suspend an app's access to your API

  1. Log in to the platform and go to your API's Details page.
  2. On the left menu bar, choose Apps.
  3. Find the app/contract on the list. On the right, click the arrow to see what actions are available.
  4. Click Suspend. At the prompt, enter a comment and click Confirm. The contract is suspended and the Resume button displays.

How do I resume an app's access to my API after I suspend it?

If you have previously suspended an app's access to your API, you can reinstate it using the Resume function.

Note: Suspend and Resume actions are available only to the API Admin; the app developer cannot suspend/resume a contract.

To resume an app's access to your API

  1. Log in to the platform and go to your API's Details page.
  2. On the left menu bar, choose Apps.
  3. Find the app/contract on the list. On the right, click the arrow to see what actions are available.
  4. Click Resume. At the prompt, enter a comment and click Confirm.

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 (see How do I export an API?).

However, you might want to export a specific contract. You can do that on the 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. Go to APIs > My APIs > choose API > 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 dialog, 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).

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 Live implementations, 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.

Why is there a separate Activate step for contracts in the Live implementation?

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.
  • Live: 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 Live implementation. 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 access is granted to the Live implementation.
  • 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 instead would limit those rights to a subset of API Admins who have an additional role.