<API Proxy Name>
API Proxy Documentation
<Customer>, <Project Name>
Author
©2013 Apigee. All Rights Reserved.
Revision History
Date
<date>
Version
<version>
Description
<description>
Author
<author>
©2013 Apigee. All Rights Reserved.
Table of Contents
Purpose
1
Prerequisites
1
ProxyEndpoint
1
PreFlow
1
Request
1
Response
1
Custom Flows
1
PostFlow
1
Request
1
Response
1
HTTPProxyConnection
2
TargetEndpoint
2
PreFlow
2
Request
2
Response
2
Custom Flows
2
PostFlow
3
Request
3
Response
3
HTTPTargetConnection
FaultRules
Custom Flows
DefaultFaultFlow
Appendix
3
3
3
3
4
Key Concepts and Terminology
4
Supporting Documents
4
©2013 Apigee. All Rights Reserved.
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-proxyconfiguration-reference>
ProxyEndpoint
All policies listed below are **REQUIRED** unless denoted as [OPTIONAL].
PreFlow
Request
1.
2.
3.
ValidateApiKey - Validates the the API key. Configured to look at the query parameter apikey.
SetConfigurationVariables - Assigns variables from the client request that can be referenced throughout the
message flow.
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
©2013 Apigee. All Rights Reserved.
2.
3.
as an example placement of the policy. It should execute all logic in the response flow, except format marshaling for
the client.
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.
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/>
<!-- Default VH = HTTP(80) and https_vhost - HTTPS(443) -->
<VirtualHost>default</VirtualHost>
<VirtualHost>https_vhost</VirtualHost>
</HTTPProxyConnection>
TargetEndpoint
All policies listed below are **REQUIRED** unless denoted as [OPTIONAL].
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.
©2013 Apigee. All Rights Reserved.
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.
All policies listed below are **REQUIRED** unless denoted as [OPTIONAL].
1.
2.
3.
XmlToJson - XMLtoJson policy. This policy performs XML to JSON conversion on the payload.
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.
SetJSONTemplateMessage - AssignMessage policy. It is conditionally executed based on the values of the request
header Accept.
©2013 Apigee. All Rights Reserved.
4.
5.
SetXMLTemplateMessage - AssignMessage policy. It is conditionally executed based on the values of the request
header Accept.
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
<Concept>
Description
<Describe the meaning to facilitate understanding of audiences not familiar with
Apigee terminology or specific terms adopted by the project>
Supporting Documents
Document Title
[Provide Document title.]
Description
[Provide description of the document.]
Location
[Provide location of the document.]
©2013 Apigee. All Rights Reserved.
