API Mashups

Servers that provide an API may expose a vast set of functionality. However, each individual service in the API usually provides a very specific functionality. While this is usually effective, sometimes it is useful or required to consolidate a few services and expose them as a single service. In other situations, you might want to extend a service with the functionality provided by an external API. API mashups address these requirements for grouping services and exposing them as a single service.

Note:
Currently, API Gateway supports API mashups for REST APIs only. You can define a mashup only in a REST API and only REST APIs can be included in the mashup.

The APIs that are included in an API mashup (participating APIs) can be connected to each other in the following ways:

API chaining. Two or more participating APIs are connected and invoked in a sequence—one after the other.

API aggregation. Two or more participating APIs are connected to a common aggregator step. The aggregator step captures the response of the aggregated APIs. The aggregator step enables you to:

Assume an API that provides information about courses offered by different universities in a given location. This API provides a service that returns the list of universities for a given course name and postal code. This service could be:

The provider of the API wants to extend this API for use in mobile applications that have access to users’ location. As mobile applications can access a user’s location in terms of longitude and latitude, this involves first retrieving the postal code for the users’ current location and then passing that information to the existing API.

Suppose there is a publically available API that returns the postal code based on longitude and latitude values. This service could be:

If this public API meets other requirements, such as security, performance, and usage limits, it can be utilized to deliver the required functionality.

Using an API mashup, you can create and expose a single service that calls both services: the external service that returns the postal code and the existing service that provides the list of universities. The resulting service could be:

Assume an IT services provider that provides hosting and cloud services to its customers. Users can create accounts for the different types of services that they need to use: bare metal servers, Virtual Private Servers, platforms as a service, and so on. A customer has multiple types of accounts. The statement for each type of account is returned by a different API. The API provider wants to provide a single API that consolidates the statements of a given customer and returns a single response with all the information.

An API mashup allows you to orchestrate multiple resources and methods and expose the behavior as a single service. In a regular method that is not a mashup, API Gateway applies all the enforced policies and then routes the request to the native endpoint. In the case of a mashup, API Gateway still applies all the enforced policies in the request flow till routing; but thereafter, it starts the orchestration flow defined in the mashup. After the orchestration flow ends, all the policies defined for that method are applied in the response flow—in the same way as a regular method.

API mashups are defined at the method level. You can edit any REST API and define a mashup for one or more methods within it.

You can include any REST API defined within API Gateway in the mashup.

The entire framework that API Gateway provides to a regular REST API method is available to an API mashup method. Therefore, you can utilize query parameters, path parameters, aliases, variables, payload transformations using XSLT transforms, transformations using webMethods IS services, and custom pipeline variables.

By default, the policies of an API that is participating in an API mashup are not enforced when it is invoked within the API mashup. However, if you select the Should execute Outbound policies option, the outbound security policies of the participating API are enforced in the context of the API mashup.

The following are specific to a mashup step and are not automatically passed from one step to another:

An exception to this rule is the first step (the first participating service) in a mashup, which receives the complete request sent by the client.

A participating API cannot have reverse invoke routing.

An API mashup consists of one or more mashup steps, and each step invokes an API. A mashup step defines the request for the API that it invokes. A step can use the data objects provided by API Gateway to access data in the initial request sent to the operation that has the mashup and any of the previous steps.

Object/Variable Type	Possible values
paramStage	request response
paramType	payload or body headers query path httpMethod statusCode statusMessage
queryType	xpath jsonPath regex

${paramStage.paramType}

You can use this syntax to access the following string variables: path, statusCode, statusMessage, httpMethod. Examples: ${request.path}, ${response.statusCode}

${paramStage.paramType.paramName}

You can use this syntax to access map types, such as query, headers, and path. Example: ${request.query.var1}, ${response.header.Content-Type}, ${request.path.name}.

${paramStage.paramType.queryType[queryValue]}

Where //ns:emp/ns:empName is the XPath to be applied on the payload if contentType is application/xml, text/xml, or text/html.

Where $.cardDetails.number is the jsonPath to be applied on payload if contentType is application/json or application/json/badgerfish.

${paramStage[stepName].paramType.queryType[queryValue]}

You can use this syntax to access data in any step. For example, you can use the following syntax to access the payload of a step named createAPI: ${response[createAPI].payload.jsonPath[$.apiResponse.api.id]}.

You can define your own variables using the Custom Pipeline variables field:

Note:
Data objects from any of the steps of the mashup can also be accessed by response processing policies and error processing policies of the API that contains the mashup.