API Mashups

Usage scenario - API chaining

Assume an API that provides information about courses that different universities in a location offer. This API provides a service that returns the list of universities for a specific course name and postal code. This service can be as follows.

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, accessing the users' location involves the following steps.

1. Retrieving the postal code for the users’ current location.
2. Passing the information that is retrieved to the existing API.

Suppose that you have a public API that returns the postal code based on longitude and latitude values. This service can be as follows.

GET /postalcode?lat=331&long=22324321

If this public API meets other requirements, such as security, performance, and usage limits, it can be used 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 can be as follows.

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. Different APIs return the statement for each type of account. The API provider wants to provide a single API that consolidates the statements of a specific customer and returns a single response with all the information.

Key Features of a REST API Mashup

• An API mashup helps you to orchestrate multiple resources and methods and expose the behavior as a single service. In a regular method that is not a mashup, webMethods API Gateway applies all the enforced policies, and then routes the request to the native endpoint. If a mashup, webMethods API Gateway still applies all the enforced policies in the request flow up to routing; but thereafter, it starts the orchestration flow that is defined in the mashup. After the orchestration flow ends, all the policies that are 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 webMethods API Gateway in the mashup.
• The entire framework that webMethods API Gateway provides to a regular REST API method is available to an API mashup method. Therefore, you can use query parameters, path parameters, aliases, variables, payload transformations by using XSLT transforms, transformations by 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 parameters 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 that the client sends.

• A participating API cannot have a 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 that are provided by webMethods API Gateway to access data in the initial request. This initial request is 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 the 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. For example, ${key}, ${value}. The custom pipeline variables that you define are available in subsequent steps.