4 Managing APIs for Partner Applications

This chapter explains how to create, configure, and manage application programming interfaces (APIs) by using Oracle Communications Services Gatekeeper partner relationship management (PRM) portal applications.

About APIs for Partner 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 being used, the APIs associated with the applications support traditional communication services, and for internet- or enterprise-based APIs from back-end third-party services.

About the API Data

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. You can also provide a different name that is used in the access URI that your customers use to access the API (a context root).
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 the SOAP or REST protocol, its URL, encryption requirement, the exposed service resources and methods.

Configuring an API as public makes it accessible to all partners. Alternately, you can configure the API to be private and designate partner groups that are permitted to use the API.
Type of security you want to use to protect access to Services Gatekeeper API methods, and type of security you want to use to protect the API service.
Action chains to process incoming and outgoing traffic from and to the API.

For details about the API data to collect, see Services Gatekeeper Partner and API Management Portal Online Help.

About Naming Your APIs

The APIs you create can have two identifiers: a display name in the API Name field, and a different context root that identifies the API in its Access URL. The two identifiers allow you to create an API name to display in the PRM Portals that is different from the name seen by your customers. The identifiers are identical by default; if you fill in just one of these fields, that value is used for both identifiers. Once the API is created however, you cannot change these identifiers.

For example, assume that you want to name an WeatherAPI API within the PRM Portals, but want to present WeatherSouthWestAPI as the name in the access URI that users see. When creating the API in the Partner and API Management Portal, you could specify WeatherAPI in the Name field, and WeatherSouthWestAPI in the Context Root field. Within the PRM Portals, the API is named WeatherAPI, but users of the API access it using this URI:

http://IP_Address:port/WeatherSouthWestAPI

The object defining the API stores the name in the apiName field and the context root in the apiDisplayName field.

Note:

An apiName can contain spaces.

About Presenting API Resources to Your Customers

The URI that you present to your customers (partners or their customers) has two components, a context root and a path. See "About Naming Your APIs" for details on the context root. This section deals with the second part of the service identifier, the path, which is often mapped to a different service path.

This resource mapping mechanism is designed to provide you with the flexibility to use a different internal URL structure than the one you present to customers. You can also potentially change the internal URL structure without your customers having to alter their request messages. This is particularly useful if your Services Gatekeeper implementation uses REST to communicate.

You present services or resources to customers by defining each of them in the API Resource table. If the URLs that users send to an API are different from the URLs of a specific resource or service, you can use the Resources table to map one to the other. Figure 4-1 shows the Resource table that each API uses with a sample resource in it.

Note:

If you create an API from an existing WSDL or WADL file, the API Resource Table is automatically populated with the resources from the file.

Figure 4-1 The Services Gatekeeper API Resource Table

This graphic is described in the surrounding text.

You fill in these fields for each resource:

Name - an informal name to identify the resource.
Path - The path given on the incoming request message (excluding the context root). This field takes variables; see "Using Variables and Wildcard Characters in the Request Path and Service Path" for details.
Method (or Verb) - The request action. GET, POST, PUT, DELETE for REST request messages, or a SOAP Method to use.
Service Path - The service path (resource) that combination of Path and Method/Verb maps to.
Service Verb - The action to take on the resource. GET, POST, PUT, DELETE for REST request messages, or a SOAP Method to use.
Expose - Allows you specify whether to expose or hide a resource from partners.

Using Variables and Wildcard Characters in the Request Path and Service Path

You have the option to use variables or wildcards in the resource path to map different URLs sent in with a request message to a different service path for a resource. At its simplest, you can map a request path to a different service path. Table 4-1 shows a simple mapping.

Table 4-1 A Simple Path Mapping Example

Path Value	Service Path Value	Result
/value1	/value2	/value1 is mapped to /value2

Note that if the request URI is not an exact match, it is not mapped. For example if the path value in Table 4-1 was /value1/extra, it would not be mapped to /value2 because it does not exactly match /value1.

Table 4-2 shows more examples of mapping request message paths to service paths.

Table 4-2 Example Path Value Mapping With Wildcards and Variables

Path Value	Service Path Value	Result
/value1*	/value2	/value1 is mapped to /value2 /value1/value3 is mapped to /value2
/value1*	/value2*	/value1 is mapped to /value2 /value1/value3 is mapped to /value2/value3
/value1/{var1}/value3	/value2/{var1}/value4	/value1/123/value3 is mapped to /value2/123/value4
/value1/{var1}/{var2}	/value2/{var2}/{var1}	/value1/abc/123 is mapped to /value2/abc/123
/value1/{var1}/{var2}	/value2	/value1/abc/123 is mapped to /value2

Resource path wildcard and variable rules:

The "*" wildcard character can only be used at the end of a path. That is, you cannot use this syntax: /*/value1
You cannot change the HTTP method for the matched IP addresses with variables or wildcard characters.
The varn string is only an example; you can replace it with any string you want. Just remember to put variable strings inside curly brackets "{}", ensure that the strings are identical, and ensure that the values they match are identical.
The variables can include more than one path layer separated by slash "/" characters. For example {var1} could map to /value12/abc/123.

About the Status of an API

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 are 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:
  1. Contact the partner who owns the application offline.
  2. 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, applications can not access the API. 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. Also, 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.

About Temporarily Suspending APIs

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.

About API Versioning

You have the option to create an alphanumeric string to use as a versioning number for the APIs that you create. Services Gatekeeper does not do anything with the string, but it can be useful for you to keep track of your APIs. You add the string to the Version field of the Create API screen as you create the API. Or leave this string blank to omit a version number. The string uses any of the [0-9a-zA-Z\\.-_].* characters.

The syntax for the API access URL:

IP_address:port/context_root(/version_number)

Where:

IP_address :port - The IP address and port number to use to connect to the system hosting Services Gatekeeper.
context_root - the context root of the API. By default, this value is the name for the API that you entered in the Name field, but you can change it as needed.
version_number - the optional version string that you entered for the API.

This example show an access URL with a context root of apis/myapi and no version number:

http://203.0.113.18:8001/apis/myapi

You have these options for specifying a particular API/version when calling an API:

If there is no version, just send the access URL for the API. For example:

GET apis/myapi HTTP/1.1Host: 203.0.113.18:5879 http://203.0.113.18:8001/apis/myapi

or with the final "/":

GET apis/myapi HTTP/1.1Host: 203.0.113.18:5879 http://203.0.113.18:8001/apis/myapi/

Specify the version number after the context root. This example access URL matches myapi version 2:
```
GET apis/myapi HTTP/1.1Host: 203.0.113.18:5879 http://203.0.113.18/apis/myapi/2
```

Specify the version number in the HTTP request Accept header. For example:

GET apis/myapi HTTP/1.1Host: 203.0.113.18:5879
Accept: 203.0.113.18/apis/myapi+json;version=2

Providing API Credentials to Partners

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.

Creating APIs for Use in Partner Applications

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.

Manipulating HTTP Query Parameters in API Messages

You can change HTTP query parameters using these API components in this order:

A request message
The message request URL
An API Resource Service Path
Using a Custom Action
- Using the withoutQueryParameter method to remove the query string
- Using withQueryString to change the query string or withQueryParameter method to overwrite the query parameter value. These are methods to the CalloutBuilder class in the Actions Java API. See the ”All Classes” section of the Java API Actions Reference documentation.

In other words, a query string in a request message can be changed by any of these components, but it is the last component to change it that sets the final string value.

See "Using Actions to Manipulate HTTP Query Parameters" for information on using actions to change your query parameters.

Securing Services Gatekeeper Methods and API Services

This section explains the types of security you need to consider when creating an API:

Securing the Services Gatekeeper API Methods
Securing the API Service

Securing the Services Gatekeeper API Methods

You use the Exposed API Security settings when creating an API to select a method for authenticating applications attempting to use methods in the Services Gatekeeper API. Used with all types of APIs. You have these options:

TEXT - Requires the application to provide a user name and password. Can be used with OAuth. Requires that you set the EnableSouthCookie performance setting to true. See "Setting Actions System Performance Settings" for instructions.
OAuth - Allows the application to access third-party resources. Can be used with TEXT-based security.
AppKey - Requires the application to authenticate itself using an application key. Especially useful for applications that cannot otherwise identify themselves. By default Services Gatekeeper searches the x-api-key query parameter for the key first, then the header. You can change this behavior using the AppKeyValidation action in an action chain. See "Understanding Front and Middle Actions" for details on the AppKeyValidation action.

Securing the API Service

If you create an API using the Existing URL or Existing WADL/WSDL File selections you use one of the Service Security option to securing the API service (sometimes called a backend service). You have these Service Security options:

None - Allows unauthorized access to the API service.
Text - Text-based security relies on a username and password to protect the API service. You are asked to provide the user name and password for the account that monitors and manages the traffic. Can be used with OAuth security.
OAuth - OAuth-based security allows you to provide access to third-party resources requiesYou are asked to provide:
- 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.

If you are creating an API using the Registered Network Service selection, Services Gatekeeper takes this security setting and parameters from the interface you created using the Network Service Supplier Portal. If you are creating an API using the Existing Communication Service selection, Services Gatekeeper takes this setting from the underlying communication service plugin.

Configuring Actions Chains to Manage API Traffic

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 manage and manipulate the information in the requests and responses. See "Using Actions to Manage and Manipulate API Traffic" for information.

Understanding the API Back-end Server Configuration

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

Updating APIs

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.

About an API Status and Modifications to its Data

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.
- Modify the action chain, including add or remove actions, or change an action (for example, change the service level agreement to raise or lower a rate), or other action details.
- 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.

Suspending Applications from Using an API

You can suspend an application from using an API by using the Suspend button on the API Applications tab in the Partner and API Management Portal. This button toggles between Suspend and Un-Suspend states for the application. In the suspended state the application can not access the API. See the Services Gatekeeper Partner and API Management Portal Online Help for details.

Removing APIs

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.