· Web viewThis solution documentation will cover the base architecture and design for API proxies built on Apigee Edge. The base architecture and designed (template) can be referenced

©2013 Apigee. All Rights Reserved.

<API Proxy Name>API Proxy Documentation<Customer>, <Project Name>

Author


Revision HistoryDate Version Description Author<date> <version> <description> <author>


Table of Contents

Purpose 1Prerequisites 1ProxyEndpoint 1

PreFlow 1Request 1Response 1

Custom Flows 1PostFlow 1

Request 1Response 1

HTTPProxyConnection 2TargetEndpoint 2

PreFlow 2Request 2Response 2

Custom Flows 2PostFlow 3

Request 3Response 3

HTTPTargetConnection 3FaultRules 3

Custom Flows 3DefaultFaultFlow 3

Appendix 4Key Concepts and Terminology 4Supporting Documents 4


Purpose

This solution documentation will cover the base architecture and design for API proxies built on Apigee Edge. The base architecture and designed (template) can be referenced at [provide github or other link to API proxy source code].

Prerequisites

Understanding of an Apigee API proxy - Reading: <http://apigee.com/docs/gateway-services/content/api-proxy-configuration-reference>

ProxyEndpoint

All policies listed below are **REQUIRED** unless denoted as [OPTIONAL].

PreFlow

Request

1. ValidateApiKey - Validates the the API key. Configured to look at the query parameter apikey. 2. SetConfigurationVariables - Assigns variables from the client request that can be referenced throughout the

message flow.3. ResponseCache [OPTIONAL] - Response caching policy. This is used as a pair with the same policy defined in a

response flow. In the request flow, it is used as the lookup functionality of caching. This is shown in the template as an example placement of the policy. It should execute after the key validation and request information being capture. Allows for a cached response to be served as soon as possible.

Response

N/A

Custom Flows

Custom API flows are designed here. They are typically classified with a condition using the pathsuffix of a request along with the method (verb). Examples:

Create User: Flow with condition: proxy.pathsuffix MatchesPath "/users" and request.verb == "POST" Get all users: Flow with condition: proxy.pathsuffix MatchesPath "/users" and request.verb == "GET"

Every custom flow has a customizable Request and Response segment like Preflow and PostFlow.

PostFlow

Request

N/A

Response

1. ResponseCache [OPTIONAL] - Response caching policy. This is used as a pair with the same policy defined in a request flow. In the response flow, it is used as the populate functionality of caching. This is shown in the template


as an example placement of the policy. It should execute all logic in the response flow, except format marshaling for the client.

2. XmltoJson - XMLtoJson policy. This policy performs XML to JSON conversion on the payload. This policy should have a condition to support the proper use of request header Accept.

3. SyslogPolicy - Message Logging via Syslog. This policy is used for sending information about the request to a syslog server.

HTTPProxyConnection

Example configuration is below.

BasePath configuration should following the versioning standards set in [provide link to Development Standards]. The virtual host definitions MUST match the below example as defined in proxy-template API proxy. The virtual

hosts defined in each environment within Apigee Edge are named default (http) and https_vhost (https).

<HTTPProxyConnection> <BasePath>/proxy-template</BasePath> <Properties/>  <VirtualHost>default</VirtualHost> <VirtualHost>https_vhost</VirtualHost>

</HTTPProxyConnection>

TargetEndpoint


PreFlow

N/A

Request

N/A

Response

N/A

Custom Flows

Custom API flows are designed here. They are typically classified with a condition using the pathsuffix of a request along with the method (verb). Examples:

Create User: Flow with condition: proxy.pathsuffix MatchesPath "/users" and request.verb == "POST" Get all users: Flow with condition: proxy.pathsuffix MatchesPath "/users" and request.verb == "GET"

Every custom flow has a customizable Request and Response segment like Preflow and PostFlow.


PostFlow

Request

N/A

Response

N/A

HTTPTargetConnection

Example configuration is below.

The properties connect.timeout.millis and io.timeout.millis must be configured. These are the timeouts imposed between Apigee and the TargetEndpoint connection. The connect property is for establishing the http or https connection while the io property is the response read timeout.

<HTTPTargetConnection> <Properties> <Property name="connect.timeout.millis">30000</Property>

<Property name="io.timeout.millis">30000</Property> </Properties> <URL>http://www.apigee.com</URL> </HTTPTargetConnection>

FaultRules

[The FaultRules code can be different in each Endpoint configuration; however, this example has them being the same in each and is the reason for FaultRules being it’s own document section alongside ProxyEndpoint and TargetEndpoint. If they are separated, please include a FaultRules subsection within the ProxyEndpoint and TargetEndpoint sections.]

The base configuration that's documented in this template is **REQUIRED**. You can define custom fault processing flows here, using a condition just like a custom flow.

Custom Flows

DefaultFaultFlow

Condition: none. This flow will always match when the request is sent to fault processing due to a RaiseFault policy, policy error, or non-success response from an endpoint.


1. XmlToJson - XMLtoJson policy. This policy performs XML to JSON conversion on the payload. 2. GenericFaultHandling - Javascript policy. This policy provides the basis for supporting a generic DefaultFaultFlow

flow inside of an Apigee proxy. This policy will ensure that the fault information is set correctly for use in later syslog execution and response message assignments.

3. SetJSONTemplateMessage - AssignMessage policy. It is conditionally executed based on the values of the request header Accept.


4. SetXMLTemplateMessage - AssignMessage policy. It is conditionally executed based on the values of the request header Accept.

5. SyslogPolicyFaultRules - Message Logging via Syslog. This policy is used for sending information about the request to a syslog server. It is custom for FaultRules since information is retrieved from different sources.

Appendix

Key Concepts and Terminology

Term/Concept Description<Concept> <Describe the meaning to facilitate understanding of audiences not familiar with

Apigee terminology or specific terms adopted by the project>

Supporting Documents

Document Title Description Location[Provide Document title.] [Provide description of the document.] [Provide location of the document.]