This chapter describes how you can configure and manage application programming interfaces (APIs) by using Oracle Communications Services Gatekeeper API management platform and its partner relationship management (PRM) portal applications.
An API for a partner application contains all the information required to use the interface. Service providers or partner managers create and manage APIs in Partner and API Management Portal and application developers or partners use them in Partner Portal.
Services Gatekeeper enables you to publish an API based on any HTTP URI. To create an API, you select a network interface from the types of network interfaces or communication services the network supports, and configure the API. You can expose the API publicly to all partner groups or restrict it to selected partner groups. To assist partners in subscribing to the API, you also provide the URL to the location hosting the necessary documentation on the API.
In Partner Portal, partners subscribe to these APIs in the applications they create. When partner applications are active and in use, the APIs associated with the applications provide support for traditional communication services and for internet- or enterprise-based APIs from back-end third-party services.
Before you begin configuring an API in Partner and API Management Portal, collect the following data about the API:
Basic information to identify the API, consisting of a unique name and version number, and a short description.
Type of interface, such as a URL for the existing Web service, an existing WADL/WSDL file, a registered network service, or an existing communication service. For the selected interface, the details about the interface, and the network security provided for it.
URL to the documentation on this API.
Type of exposure for the API, specifying whether the API interface uses SOAP or REST protocol, its URL, encryption requirement, the exposed service resources and methods.
Configure an API as a public API to make it accessible to all partners. Alternately, you can configure the API to be private and designate the partner groups who are permitted to use the API.
Action chains to process incoming and outgoing traffic that makes a call to the API.
For details about the API data to collect see Services Gatekeeper Partner and API Management Portal Online Help.
Each of the APIs in the portals has an assigned status. The current state of an API indicates whether the API is available for use, is modifiable, or no longer in service.
A partner manager manages the status of an API from the time that the API is created to the time when the partner manager removes it from the portals. As the partner manager, you update the status of the API in the Life Cycle tab of the API page in Partner and API Management Portal.
CREATED
When a partner manager creates an API in Partner and API Management Portal, Services Gatekeeper stores the data on the API and assigns the status of the API as CREATED.
APIs with CREATED status are in an unpublished state and are not visible in Partner Portal. They can be viewed in Partner and API Management Portal only and modified in that application.
You can change the state of an API from CREATED to PUBLISHED. If a partner manager decides to discard a created API instead of publishing it, the API is removed.
PUBLISHED
A partner manager changes the status of a newly created API to PUBLISHED in Partner and API Management Portal. Then, Services Gatekeeper makes the API available to all partner groups or to designated partner groups, based on the API configuration.
Partners can subscribe to the APIs when they create their applications.
All modifications to a published API are performed in Partner and API Management Portal only. You can change the state of an API from PUBLISHED to:
DEPRECATED, when a newer version of the API is published
SUSPENDED, if necessary
Important:
If you deprecate an API for which you are not providing a newer version, applications that currently use the API will be affected. Check the Applications tab for the API to verify that the tab does not list any application.If the Applications tab lists one or more applications, then, do the following before you change the status the API.
For each application:
Contact the partner who owns the application offline.
Ensure that your partner takes the required actions to safeguard the applications.
DEPRECATED
A deprecated API represents an older version of an API.
Deprecated APIs are not available to new applications. A deprecated API is available to applications that subscribed to it until the end of the effective period set for the API. After that, an application's attempts to access the API fail. It is the partner's responsibility to access all current applications that used the prior API and modify them so that they call the updated API.
All calls to the prior version of the API are supported until the date when the API is suspended or removed from portal views. From then on, all calls to the prior API version fail and the request receive the 404 error response.
You can change the state of an API from DEPRECATED to one of the following in Partner and API Management Portal:
SUSPENDED
PUBLISHED, when the API is required by partners and there is no other API with the same name in the system.
SUSPENDED
When a deprecated API reaches the final date set by the partner manager, Services Gatekeeper notifies all partners. Additionally, an API can be temporarily withdrawn from circulation by a partner manager in Partner and API Management Portal.
Note:
When a partner manager suspends a deprecated API that is still in use by applications, Services Gatekeeper displays a warning in Partner Manager. If the partner manager continues with the suspension of the API, the associated applications may be affected.In either scenario, the API is considered to be in a suspended state and the URL for the API is no longer valid. Calls made to a suspended API return a 404 error response.
At times, you may want to temporarily block the use of an API that you published and made available one, some, or all partner groups. This scenario occurs if there is an issue with an API and the resolution process for that issue requires you to disable the API temporarily. In such a situation, you can suspend the API temporarily and notify the partner groups whose applications are affected by this suspension.
After a partner manager approves an API application registration, the Partner and API Management portal returns an application instance ID and authentication credentials to the requesting partner. The partner then uses the instance ID and credentials to sent traffic through Services Gatekeeper to the application. The credentials include both a Traffic User Password for basic authentication, and an Access Token for OAuth authentication.
The MBean attribute DafExpireTime has been added to the OAuthCommonMBean to control how long the Access Token is valid. The default value is 3600 seconds.
To create an API, enter the details for the API on Partner and API Management Portal. The supported types of interfaces are:
A WADL or WSDL file for the API containing some methods or resources defined for the API.
The connection to a network interface that does not have a WADL or WSDL file.
The connection to a network service from a set of network services maintained by Network Service Supplier Portal.
The connection to an existing Services Gatekeeper communication service.
Use the Create API page of Partner and API Management Portal to enter the details about the API interface.
When end users use your partner applications, the applications generate requests and responses that call upon one or more of the subscribed APIs created in Partner and API Management Portal and supported by Services Gatekeeper.
You can set up actions to filter and act on incoming and outgoing messages that contain calls to the APIs subscribed to by your partner applications. See:
You can use the actions provided by Services Gatekeeper and configure other actions to be implemented on the request (or response). You can set up actions chains to take a wide range of real-time effect on the request or response, such as identity management, mapping to support data formats and protocol changes, authorization, logging, monitoring, and statistics.
The sequence of actions in the action chain depends on the direction of the message flow, whether it is application-initiated and travelling to the network or server-initiated and travelling to the application. Some actions (such as identity management) are valid in the request flow and some in the response flow only. Other actions (such as supporting protocol changes, validations) are common in that they are applicable in either direction.
The Actions tab of an API provides easy to use icons that you can drag and drop into the request and response flows. When you position an action incorrectly in a chain, Partner and API Management Portal prompts you to ensure that the sequence of actions is valid for that direction. The API proxy service uses the XML file to process the incoming or outgoing request and to perform required actions.
Server-initiated flows occur when, for example, an application sets up a notification for an event. The server listens for the event and sends a notification to the application. The notification comes in to Services Gatekeeper as a request from the server and contains a call to an API subscribed to by the application. The API proxy receives the request from the server and processes it according to the action chain preconfigured by the partner manager in Partner and API Management Portal. The final step in the action chain would be to forward the outbound HTTP Request to the application in the format required by that application.
When the application responds to this notification, the API proxy processes that response according to the tasks preconfigured for that sequence of the action chain. Finally, the response for the server-initiated request is sent back to the server.
When an application sends a request that contains a call to an API subscribed to by the application, Services Gatekeeper routes the request to an advanced API proxy. This proxy is a servlet that can receive and handle incoming HTTP requests such as SOAP, REST, or XML-RPC. The API proxy checks the incoming request and performs preconfigured tasks related to enforcing policy (associated with the service level agreement), transformation of the API as necessary (such as from JSON to XML format). In addition, it performs any custom tasks you added to suit your requirements. The final step in the action chain would be to forward the outbound HTTP Request to the server.
The API proxy receives the response from the server and then performs the tasks preconfigured for that sequence of the action chain. Finally, the response for the request is sent back to the application in the format required by that application.
Use front actions as major filters on the incoming request and provide identity management, monitor and safeguard network usage and so on. For example, you can use Throttling to regulate the usage of the API and regulate the traffic passing through the network based on specific partner groups. (API management already provides throttling based on the application and based on the network service.)
Use middle actions to act on the content of the request or response in real-time. For example, you can use Callout to performs an HTTP GET operation against the Request URL and store the response as required.
Set up an action chain to invoke on requests and responses travelling between the application and the network service.
Services Gatekeeper offers the following actions that you can invoke on requests passing through between the application and the network:
Throttling
Change the group name, rate (requests/second), quota period (days), and quota (requests per quota period) specified in the message. The data you are changing comes from the appropriate SLA.
Callout
A REST Call-out. Performs an HTTP GET operation against the RequestUrl and puts the response into the value of the storeResponse field. You can also change attributes of the incoming request.
Groovy
Use a Groovy language script to change any aspect of the message. For example you can add Groovy code to change the message's content, destination, status, and so on. The script can be as simple or complex as your implementation requires. This option requires knowledge of the Groovy programming language.
Json2Xml
This action takes the information in JSON protocol from the body of the incoming JSON request or response body and puts it in XML format in the body of the outgoing request or response.
SchemaValidation
Services Gatekeeper validates an incoming request or outgoing response that accesses a web service API, based on the schema provided by you for the API.
Provide values for the first XSD in the fields under the unit numbered 0. The first in the list is the main XSD/WADL/WSDL. The other entries are referenced from the first entry in the list.
For the Content parameter, enter the actual XML Schema XSD content. Paste in a Schema in the Value column.
For the Name parameter, enter the reference to the entry in Content. Use this name from another action or groovy action to retrieve the schema you entered for Content.
To add more units, click the - sign next to Un.... and repeat.
Note:
If you add the SchemaValidation action to a flow but you do not provide a schema definition for the web service API, Services Gatekeeper returns an error.Xml2Json
Convert an XML-formatted message into the JSON format.
XSLT
Use an Extensible Stylesheet Language script to change the XML-formatted body of the message.
You specify an access URL for each API that you manage using Partner and API Management portal. For multi-tier Services Gatekeeper implementations, the Partner and API Management portal provides back-end server configuration settings that you use to provide alternatives to the access URL in cases where:
The traffic is mobile-originated (network to application). In this case the traffic must be directed to the network tier server.
The back-end cluster has a public URL that is preferable to the access URL.
The back-end server only supports SSL communication. You can provide an alternative that does not require it.
You specify Partner and API Management portal back-end server configuration settings by selecting the Settings in the Header bar, then Selecting Configuration, and then filling out the back-end Server section of System Configuration section.
If your configuration is not one above, the system fills the back-end server with the following default data. For:
Multi-Tier installations: Access tier address and port
Single-Tier installations: Node address and port
At times, when an API has been in use, service providers and/or application developers may change some configured settings for the API. You can update an API by adding more resources to it or publish a newer version of the API. To modify an API, you select the API from the list of APIs in Partner and API Management Portal and make the necessary changes.
For details on updating an API in Partner and API Management Portal, see Services Gatekeeper Partner and API Management Portal Online Help.
Partner managers can modify the configuration of an API in Partner and API Management Portal. However, the following restrictions apply and are based on the current status of the API:
CREATED: Partner managers create APIs. They can modify all the fields in an API when it is in the created, unpublished state.
Partners do not have access to APIs that are set to CREATED.
PUBLISHED or DEPRECATED: Partner managers have access to published and deprecated APIs. Partners have access to APIs that are set to PUBLISHED. When an API is deprecated, some applications may be supported by a deprecated API, for a defined period, but the partner does not have access to the API.
If the API is in a PUBLISHED or DEPRECATED state, partner managers can do the following:
Modify its description.
Update the documentation link for the API.
Add more resources and expose more methods.
Change the encryption level by adding the HTTP or HTTPS setting.
Modify a private API to make it public and available to all groups. For a private API, add more partner groups to increase its availability to intended customers.
Edit the API action chain. For example, a partner manager can set the service level agreement to a very low rate.
Important:
To enable you to maintain backward compatibility of active APIs, Services Gatekeeper permits the addition of resources, access settings, partner groups, and accessibility.It does not permit any reduction to these elements in active APIs.
SUSPENDED: Suspended APIs are not modifiable, by default.
However, if there is some technical or business-related issue, the partner manager may temporarily block the API. See "About Temporarily Suspending APIs". Any change to a suspended API is made to resolve an issue. All changes fall within the above restrictions.
When you create an API for use by partners, you provide a name and a version number to identify the API. The API management platform combines the name and version number to identify the API. This combination must be unique. For example, if you have an API named mylocation with a version number 1, you cannot create or save another API named mylocation with a version number 1.
You can have multiple versions of an API. However, at any given time, only one version is published and available for inclusion in newly-created applications. The remaining versions are either in a deprecated, suspended state. You can have more than one version of an API in a deprecated state.
APIs that are in a CREATED state and not associated with any application can be removed from the portals. APIs that are in a SUSPENDED state and not in dispute can also be removed from the portals.
As a partner manager you access the API List page in Partner and API Management Portal, select the specific API icon, and click its trash icon (displayed within the API icon) to remove an API.
Partner managers can monitor the use of APIs using the Statistics and reporting package provided in Partner and API Management Portal. Partners manage the APIs made available to them with reference to the applications in which the APIs were subscribed. See "About the Reports" for a list of the API-related reports.