Using policy composition

<AssignMessage name="GenerateGeocodingRequest">
  <AssignTo createNew="true" type="request">GeocodingRequest</AssignTo>
  <Set>
    <QueryParams>
      <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
      <QueryParam name="region">{request.queryparam.country}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
    <Verb>GET</Verb>
  </Set>
  <!-- Set variables for use in the final response -->
  <AssignVariable>
    <Name>PostalCode</Name>
    <Ref>request.queryparam.postalcode</Ref>
  </AssignVariable>
  <AssignVariable>
    <Name>Country</Name>
    <Ref>request.queryparam.country</Ref>
  </AssignVariable>
</AssignMessage>

Here's a brief description of the elements in this policy. You can read more about this policy in Assign Message policy.

• <AssignMessage name> - Gives this policy a name. The name is used when the policy is referenced in a flow.
• <AssignTo> - Creates a named variable called GeocodingRequest. This variable encapsulates the request object that will be sent to the backend by the ServiceCallout policy.
• <QueryParams> - Sets the query parameters that are needed by the backend API call. In this case, the Geocoding API needs to know the location, which is expressed with a postal code, and a country ID. The app user supplies this information, and we simply extract it here. The sensor param is required by the API, and is either true or false, and we just hardcode it to false here.
• <Verb> - In this case, we are making a simple GET request to the API.
• <AssignVariable> - These variables store the values we are passing to the API. In this example, the variables will be accessed later in the response returned to the client.

Send the request with ServiceCallout

The next step in the policy composition sequence is to create a ServiceCallout policy. The ServiceCallout policy, listed below, sends the request object that we created in the previous AssignMessage policy to the Google Geocoding service, and saves the result in a variable called GeocodingResponse.

<ServiceCallout name="ExecuteGeocodingRequest">
  <Request variable="GeocodingRequest"/>
  <Response>GeocodingResponse</Response>
  <HTTPTargetConnection>
    <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
  </HTTPTargetConnection>
</ServiceCallout>

Here's a brief description of this policy's elements.

• <ServiceCallout> - As with the previous policy, this one has a name.
• <Request variable> - This is the variable that was created in the AssignMessage policy. It encapsulates the request going to the backend API.
• <Response> - This element names a variable in which the response is stored. As you will see, this variable will be accessed later by the ExtractVariables policy.
• <HTTPTargetConnection> - Specifies the target URL of the backend API. In this case, we specify that the API return a JSON response.

Now we have two policies, one that specifies the request information needed to use the backend API (Google's Geocoding API), and the second one that actually sends the request to the backend API. Next, we'll handle the response.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>GeocodingResponse</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
       <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
       <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

The key elements of the ExtractVariable policy are:

• <ExtractVariables name> - Again, the policy name is used to refer to the policy when it is used in a flow.
• <Source> - Specifies the response variable that we created in the ServiceCallout policy. This is the variable from which this policy extracts data.
• <VariablePrefix> - The variable prefix specifies a namespace for other variables created in this policy. The prefix can be any name, except for the reserved names defined by Edge's predefined variables.
• <JSONPayload> - This element retrieves the response data that is of interest to us and puts it into named variables. In fact, the Geocoding API returns much more information than latitude and longitude. However, these are the only values we need for this sample. You can see a complete rendering of the JSON returned by the Geocoding API in the API's documentation. The values of geometry.location.lat and geometry.location.lng are simply two of the many fields in the returned JSON object.

It may not be obvious, but it's important to see that ExtractVariables produces two variables whose names consist of the variable prefix (geocoderesponse) and the actual variable names that are specified in the policy. These variables are stored in the API proxy and will be available to other policies within the proxy flow, as you will see. The variables are:

• geocoderesponse.latitude
• geocoderesponse.longitude

Most of the work is now done. We have created a composite of three policies that form a request, call a backend API, and parse the returned JSON data. In the final steps, we'll feed data from this part of the flow into another AssignMessage policy, call the second backend API (Google Elevation API), and return our mashed up data to the app developer.

<AssignMessage name="AssignElevationParameters">
<Remove>
    <QueryParams>
      <QueryParam name="country"/>
      <QueryParam name="postalcode"/>
    </QueryParams>
  </Remove>
  <Set>
    <QueryParams>
      <QueryParam name="locations">{geocoderesponse.latitude},{geocoderesponse.longitude}</QueryParam>
      <QueryParam name="sensor">false</QueryParam>
    </QueryParams>
  </Set>
</AssignMessage>

If you examine the Google Elevation API, you will see that it takes two query parameters. The first is called locations and its value is the latitude and longitude (comma-separated values). The other param is sensor, which is required and must be either true or false. The most important thing to note at this point is that the request message we create here does not require a ServiceCallout. We don't need to call the second API from a ServiceCallout at this point because we can call the backend API from the proxy's TargetEndpoint. If you think about it, we have all the data we need to call Google Elevations API The request message generated in this step does not require a ServiceCallout, as the request generated for the main request pipeline, and so will simply be forwarded by the ProxyEndpoint to the TargetEndpoint, following the RouteRule configured for this API proxy. The TargetEndpoint manages the connection with the remote API. (Recall that the URL for the elevation API is defined in the HTTPConnection for the TargetEndpoint. Elevation API documentation if you would like to know more. The QueryParams that we stored previously, country and postalcode, are no longer needed, so we remove them here.

Brief pause: Back to the flow

At this point, you may wonder why we aren't creating another ServiceCallout policy. After all, we created another message. How does that message get sent to the target, the Google Elevation API? The answer is in the <RouteRule> element of the flow. <RouteRule> specifies what to do with any remaining request messages after the <Request> part of the flow has executed. The TargetEndpoint specified by this <RouteRule> tells the API proxy to deliver the message to http://maps.googleapis.com/maps/api/elevation/xml.

If you downloaded the sample API proxy, you can find the TargetProxy XML in the file doc-samples/policy-mashup-cookbook/apiproxy/targets/default.xml.

<TargetEndpoint name="default">
  <HTTPTargetConnection>
    <!-- This is where we define the target. For this sample we just use a simple URL. -->
    <URL>http://maps.googleapis.com/maps/api/elevation/xml</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Now, we just need to process the response from the Google Elevation API and we're done.

$ curl "http://{myorg}-test.apigee.net/policy-mashup-cookbook?country=us&postalcode=08008"

The response includes the geocoded location for the center of the postal code provided by the app end user, combined with the elevation at that geocoded location. The data was retrieved from two backend APIs, mashed up with policies attached to the API proxy, and returned to the client in a single response.

{  
   "country":"us",
   "postalcode":"08008",
   "elevation":{  
      "meters":0.5045232,
      "feet":1.6552599030345978
   },
   "location":{  
      "latitude":39.75007129999999,
      "longitude":-74.1357407
   }
}

Summary

This cookbook topic explained how to use the policy composition pattern to create a mashup of data from multiple backend sources. Policy composition is a common pattern used in API proxy development for adding creative functionality to your API.