API Mashups
Overview
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.
Usage scenario
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:
GET /universities?course=medicine&postalcode=600012
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:
GET /postalcode?lat=331&long=22324321
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:
GET /universities?course=medicine&lat=331&long=22324321
Key Features of a REST API Mashup
![*](chapterTOC_bullet.png)
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.
![*](chapterTOC_bullet.png)
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.
![*](chapterTOC_bullet.png)
You can include any REST API defined within API Gateway in the mashup.
![*](chapterTOC_bullet.png)
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.
Considerations for Creating an API Mashup
![*](chapterTOC_bullet.png)
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.
![*](chapterTOC_bullet.png)
The following are specific to a mashup step and are not automatically passed from one step to another:
![*](chapterTOC_bullet.png)
Headers
![*](chapterTOC_bullet.png)
Query parameters
![*](chapterTOC_bullet.png)
Path parameters
![*](chapterTOC_bullet.png)
Payload
However, you can add parameters in a mashup step to access data from any of the previous steps or another source.
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.
Structure of an API Mashup
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.
The following table summarizes the data objects and variables that are available in API Gateway.
The following data objects are available to a mashup step:
${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]}This syntax can be used to query a paramType. Examples:
${request.payload.xpath[//ns:emp/ns:empName]}Where "//ns:emp/ns:empName" is the XPath to be applied on the payload if contentType is "application/xml", "text/xml", or "text/html".
${response.payload.jsonPath[$.cardDetails.number]}Where "$.cardDetails.number" is the jsonPath to be applied on payload if contentType is "application/json" or "application/json/badgerfish".
${request.payload.regex[[0-9]+]}Where "[0-9]+" is the regular expression to be applied on the payload if contentType is "text/plain".
Note:
While xpath and jsonPath are applicable only to payload, regEx can be used with both payload and path.
${paramStage[stepName].paramType.queryType[queryValue]} You can use this syntax to access data from any of the previous steps. For example, you can use the following syntax to access the payload of the step named createAPI: ${response[createAPI].payload.jsonPath[$.apiResponse.api.id]}.
![*](chapterTOC_bullet.png)
You can define your own variables using the
Custom Pipeline variables field:
Examples: ${key}, ${value}. The custom pipeline variables that you define are available in subsequent steps.