1 PRM Portals and API Management Platform Overview

This chapter provides an overview of Oracle Communications Services Gatekeeper application programming interface (API) management platform and its partner relationship management (PRM) portal applications.

About the Services Gatekeeper API Management Platform

The API Management platform of Services Gatekeeper enables you to create applications that subscribe to APIs for the services you expose. Through these applications you can provide network quality of service (QoS) control, messaging, call control, big data analytics to internal developers, partners, and third-party developers.

The Services Gatekeeper API management platform handles all requests for the APIs associated with the services it supports. You can normalize all incoming requests to a unified format for processing the requests, customize the process flow as necessary, and regulate the use of your network resources and communication web services. You can provide an API proxy for the services you want to expose, by specifying the network address for the service and the documentation you provide on the resources for the use of both internal and third-party developers.

Services Gatekeeper supports the API management platform in both single-tier and multi-tier environments. By default, the API Management platform is deployed as a single layer with the possibility to cluster nodes together. It can also be deployed in application-tier or service-tier clusters. See Services Gatekeeper Concepts for more information.

About the PRM Portals and Users

The Services Gatekeeper API platform supports the following web-based PRM portals that enable their users to play three different roles in managing the life cycle of APIs:

• Partner and API Management Portal

  You use the Partner and API Management Portal to:

  • Create and manage APIs for use in applications.

    The APIs are configured from network service interfaces (created in Network Service Supplier Portal), communication service APIs, and Web service APIs provided by Service Gatekeeper.

  • Review and approve applications that use the exposed APIs. These applications are created in Partner Portal.

  • Manage partner groups and service level agreements.

  • Configure rules as a chain or chains of actions and locate the actions in the application-initiated or service-initiated flow of the request, as appropriate.

  Your network operators and enterprise customers work with Partner and API Management Portal. They create and manage APIs, approve partner applications, manage partner groups, and also manage partner and network service supplier accounts.

  This document and the Online Help documentation refer to users of Partner and API Management Portal as partner managers.

• Network Service Supplier Portal

  Network Service Supplier Portal enables the provisioning of network resources as network service interfaces. Services Gatekeeper displays these interfaces in Partner and API Management Portal where they are used in the creation of APIs for partner applications.

  Service supplier in your group, in another group in your company, or from a separate entity (company) entirely use Network Service Supplier Portal. They require authorization to access Network Service Supplier Portal. Each network service supplier completes an online registration request displayed by Network Service Supplier Portal. The network service supplier receives an email notification from the partner manager who reviewed that request (and approved or deleted the registration request).

  This document and the Online Help documentation refer to users of Network Service Supplier Portal as network service suppliers.

• Partner Portal

  Partner Portal enables the creation of applications. Partner applications represent services that you provide and that are configured from your network resources and communication web services running on the Services Gatekeeper PRM API management platform.

  Each partner application subscribes to one or more APIs exposed by Partner and API Management Portal. When active, a partner application can successfully handle associated HTTP requests and responses to maintain quality of service and with logic targeted to improve customer satisfaction, such as setting the permissions for a request to exceed the quota limit.

  Application developers use Partner Portal and require authorization to access the portal application. Each application developer completes an online registration request displayed by Partner Portal. The application developer receives an email notification from the partner manager who reviewed that request (and approved or deleted the registration request).

  This document and the Online Help documentation refer to users of Partner Portal as partners.

Figure 1-1 shows the users of the three portals and the data they create, access, and use in the Services Gatekeeper platform.

Figure 1-1 Services Gatekeeper PRM Portal Users and Data

How the API Management Platform Works

Services Gatekeeper uses the API Management platform to intercept and process the requests and responses in real-time, based on preconfigured tasks. You configure these tasks as a chain or chains of actions in the Partner and API Management Portal and indicate the location for each action in the application-initiated or service-initiated flow of the request. When the API proxy receives a request, the proxy checks the incoming request and performs preconfigured tasks related to maintaining security (such as verifying the service level agreement), transformation of the API as necessary (such as from JSON to XML format) and any other custom actions you configure for that flow.

You can manage the endpoint routing by customizing actions either by Groovy injection methods or by using Java-based service provider interface to provide specific logic for interacting with third-party API, filtering or modifying the value in a field, and so on. See "Configuring Actions Chains to Manage Traffic Involving an API" for more information.

About the Elements that Control the Quality of Service

The quality of service a Partner Portal application provides to the end user depends on the setup of the application in Partner Portal and aspects of the setup that are determined in the Network Services and Partner and API management Portals.

The factors that determine the quality of service are:

• Service interfaces exposed by the network

• Maximum usage and throughput for the service exposed

• The API methods subscribed to in an application

• Service level agreements in effect for the API methods selected in an application

• Request limits and quotas for the partner group (to which an application belongs)

• Interceptors and action elements that act upon the request or response in real-time

When an application developed using the PRM portals is in an active state, the API management platform receives the associated HTTP requests and proxies each request based on predefined rules set up in the portals.

About the PRM API Development Process

The process required to provide your network services as APIs to be called in real-time consists of the following tasks:

• Configuring Network Service Interfaces to Expose Your Services

• Configuring APIs to Expose Your Services For Use by Partner Applications

• Subscribing to APIs to Enhance Partner Applications

Configuring Network Service Interfaces to Expose Your Services

Network service suppliers create network service interfaces from the network resources that they want to expose. As a network service supplier, you control how partner managers (and therefore, partners) configure the usage of your network services by specifying the throughput capacity for the network resource in each network service interface you create.When the network service interfaces are employed within the configured parameters, the associated networks are safeguarded from external attacks and the resources from being overloaded.

Network service suppliers create these interfaces in Network Service Supplier Portal and Services Gatekeeper make these interfaces available in Partner and API Management Portal. Partner managers work offline with you to ensure that the network services interfaces are optimally configured for use in the network.

For example, your network group wants to market a Web service that permits applications or games to store and retrieve high scores for their games. Your network service supplier creates an interface for such a service in Network Service Supplier Portal under the name of High Score Game RESTful web service and makes it available to the network operator (partner manager). For each interface, the network service supplier provides the access URL for the interface and also information on the accessible methods of the interface.

Configuring APIs to Expose Your Services For Use by Partner Applications

As a partner manager, you use Partner and API Management Portal to create and expose APIs using the available network service interfaces and Services Gatekeeper communication services. In addition, you manage the different versions of the APIs and the life cycles of your client applications.

You exercise full control over the resource throttling and security processes by configuring elements (such as maximum usage, throughput) in the APIs you expose. In addition, you can configure each API such that you can perform some filtering action on a request or response from an application based on whether the message is in the application-initiated flow or the server-initiated flow.

Continuing with our example, you (as a partner manager) use the High Score RESTful Game web service network service interface to create and publish an API called High Score Game Notification API. In this API, you specify the maximum usage and throughput for the service exposed, provides interceptors, action elements to act upon the request or response, and information on the accessible methods.

Subscribing to APIs to Enhance Partner Applications

Partners (or application developers) use Partner Portal to register applications that subscribe to one or more APIs. Before registering the application, partners collect all the information necessary to register the application, such as name and description of the application, the time period when the application is active, the service to provide, and the rate at which the application will provide the service.

As a partner, you register an application by entering the appropriate information about the application and selecting the APIs that provide the services your application would require from the set of APIs published by your partner manager.

For each API, you specify a desired number of requests that the application sends to the network and the minimum number of requests it receives from the network within an allotted time. By doing so for each API you include in that application, you can tailor the quality of services you provide to your customers.

When you have configured such an application, you submit the application registration request to your partner manager for approval. When your partner manager approves the application, Partner Portal displays the application registration approval notification for the application. Then, you access the application in Partner Portal and set a traffic user password. With that, the application is ready for use.

In our example, an online gaming application company owns a game called Textrocks. In order to enhance the user experience for that game, the online gaming application company wants to upgrade that game with the ability to query for high scores. Your partner is associated with that online gaming application company. Your partner sees the High Score Game Notification API displayed in Partner Portal. The partner clicks the API, opens the API description document, and upgrades the Textrocks software by using the required methods of the High Score Game Notification API. When the application is approved by the partner manager, the partner sets up the traffic password and the API is then ready for use.

How Services are Deployed Using PRM Portal Applications

Figure 1-2 Steps in the PRM API Development Process

Description of ''Figure 1-2 Steps in the PRM API Development Process''

Figure 1-2 shows how the three PRM API portals deploy services in your network:

1. The network service supplier uses Network Service Supplier Portal to publish a network service interface.

2. Services Gatekeeper displays the network service interface in Partner and API Management Portal.

3. The partner manager uses the interface to create an API in Partner and API Management Portal.

4. The partner manager changes the status of the API to published in Partner and API Management Portal.

5. Services Gatekeeper displays the API in Partner Portal.

6. The partner views the API in Partner Portal. The partner creates an application that subscribes to this API and specifies the desired request limit and quota. The partner submits the application to be registered for use.

7. Services Gatekeeper displays the application registration request in Partner and API Management Portal.

8. The partner manager reviews the application registration request and approves it.

   The partner manager may also deny a request based on service level agreements and resource-related factors, such as the resource requests and quotas in effect.

9. Services Gatekeeper displays the approval (or denial) of the application registration request in Partner Portal.

10. If the application registration request is approved, the partner sets the traffic user password in the application. This password enables tracking traffic usage in the network.

    If the application registration request is rejected, the partner makes changes to it and submits the application again for approval.

Using Report Statistics to Maintain Quality of Service

Partner managers and partners can maintain a high quality of service by adjusting the API and application configurations based on the usage statistics on their APIs and applications reported by Partner Manager and Partner Portal reports.

See "Managing Application and API Usage with Report Statistics" for more information.

Security and the API Management Framework

When network service suppliers create a network service interface in Network Service Supplier Portal, they can set up the network service interface with no security, Text-based security, or OAuth protocol security.

For Text-based security, you are asked to provide a user name and password for the account that monitors and manages the traffic.

For OAuth security, you are asked to provide the following:

• Authorization URI, the URI to which the user will be sent for authentication and authorization.

• Token URI, the URI to which the user will be sent to obtain a request token. This request token acts as a temporary token and authorizes the user to use the interface.

• Client Redirect URI, the URI to which the user will be sent after a successful authentication.

PRM Portal Service Level Agreements

Partner managers create partner groups and assign each partner account that they manage to a partner group.

When a partner manager creates a partner group, for example a partner group called Platinum, the partner manager sets up a service level agreement (SLA) for that partner group. A partner group's SLA defines a partner group's request limit for a service as the number of requests per second and its quota limit as the number of requests the partner group can process and the number of days for processing the requests allowed for that group. The quota limit is an integer with a maximum value of 2147483648 requests.

When a partner manager creates an API, the partner manager can restrict the availability of that service to one or more partner groups, or expose the API to all partner groups. If the partner manager makes an API private to two groups, for example, Platinum and Gold, that API is then visible and available in Partner Portal for use in applications to partners who belong to Platinum and Gold partner groups. The API will not be available to partner accounts that belong to any other partner group in the system.

If the partner manager makes an API public, the API is visible and available in Partner Portal for all partner accounts.

Services Gatekeeper provides a default partner group called sysdefault_sp_group. When a partner manager creates or approves a partner account, Services Gatekeeper assigns that partner account to sysdefault_sp_group. This default service provider group has a blank SLA and therefore no request limits or quota allotments. Until a newly-created partner account is assigned to a different partner group, the partner who owns that account has no APIs available and cannot successfully register an application.

Partner managers can create any number of uniquely-named partner groups and change the group assignment for a partner account. At any given time, a partner account is assigned to one partner group and the partner is notified whenever there is a change to the group assignment. Partner managers also manage the partner accounts and partner groups they create and, when the need arises, they delete the partner accounts and partner groups that they created.

If a partner manager assigns a partner account to a different partner group, the partner manager must reconcile any discrepancies between the allowances stipulated by the SLA of the new partner group and the usage requirements of the applications associated with the partner account. See "Group Assignments for Partners and SLAs".

Extending the PRM API Portals

Partner managers can extend and customize portals by adding add new pages to the portals, and creating a new navigation entry points to enter these new pages. For more information, see "About Customizing PRM Portals".