Software AG Products 10.11 | Using API Gateway | APIs | API Mashups
 
API Mashups
 
Creating an API Mashup
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.
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:
*Collate the responses and pass to the next step.
*Process the responses and pass the processed data to the next step.
Usage scenario: API chaining
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
Usage scenario: API aggregation
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.
Key Features of a REST API Mashup
*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.
Considerations for Creating an API Mashup
*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:
*Headers
*Query parameters
*Path parameters
*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.
*A participating API cannot have reverse invoke routing.
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.
Object/Variable Type
Possible values
paramStage
*request
*response
paramType
*payload or body
*headers
*query
*path
*httpMethod
*statusCode
*statusMessage
queryType
*xpath
*jsonPath
*regex
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 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:
Examples: ${key}, ${value}. The custom pipeline variables that you define are available in subsequent steps.
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.