Proxy Development Guidelines
The following are
guidelines when developing a proxy. They can also be used as a checklist to
confirm best practice use. See the Proxy Template example for implementation
details.
The proxy will not deploy
as is. Go through the list below to customize before deploying.
- Name the proxy based on a
common proxy naming convention
- Example:
{businessunit}-{api-purpose/function}-proxy-v1
- Use a naming convention for
policies
- Examples:
- {policytype}.{purpose}:
AssignMessage.SetResponseMessage (recommended)
- {policytype}-{purpose}:
AM-SetResponseMessage
- {flow}.{policytype}.{purpose}:
- GetProfileDetails.AM.SetResponse
- GetProfileDetails.AssignMessage.SetResponse
- GetProfileDetails-AM-SetResponse
- Implement common error handling
- See FaultRules/DefaultFaultRule
- Add additional AssignMessage
policies to support additional error codes
- FaultRules allow you to
customize the error code per error code.
- See the policy's documentation
for a list of error codes thrown by the policy
- Use a KVM for environment
specific properties. Proxy should not contain hardcoded urls, credentials
or other properties.
- Use a target server for the
backend url
- This is needed for 2-way SSL
anyways
- Specify target endpoint path
- Specific for each resource
- Hardcode if it won't change per
environment
- Could also use KVM if the
target paths may change
- Use spike arrest to protect
against DDOS or other bursts of traffic
- Leverage custom analytics to
capture variables
- Use catchall flow to catch
requests for resources that are not defined.
- Use consistent variable names
throughout the proxy. Recommended naming convention:
- flow.request.{variablename}
- flow.kvm.{variablename}
- Remove unused policies (look
for broken chain icon)
- For major changes to the proxy,
be sure to create a new revision before making changes.
For more best
practices, see: http://docs.apigee.com/api-services/content/best-practices-api-proxy-design-and-development
Developing a proxy is
only the first part of the software lifecycle. Don't forget to continue the
process with Continuous Integration. See here for an example: https://github.com/davidmehi/api-ci-tools
edge-proxy-template
Details an Apigee Edge proxy template incorporating best
practices
This template has best practices built into the proxy. A
developer can use this template as their starting point in creating a proxy.
Save as a new proxy and customize.
Steps to customize:
- Enforce
API Key or AccessToken Verification
- Enable a
secure API by either API or Access token
- Be sure
to add one of these in the preflow
- Enforce
Spike Arrest policy and the Quota policy
- Extract
the necessary request headers, parameters, path parameters and/or payload
data
- Reference
the "ExtractVariables.CommonRequestHeaders" policy
- Fill in
the necessary resource flows.
- Replace
"getResource" and "postResource" with your resource
and verb definitions
- Add
necessary validation
- Use the "Javascript.ValidateRequestParameters"
policy as a guide. This provides a robust way to validate request headers,
parameters, path parameters and payloads using Javascript
- Add the
validation to each resource that needs it. You will need to create a copy
of this policy for each instance
- Use JSON
threat protection on POST calls
- Set
Target Server
- Define
your Target Server using the Management UI or Management API.
- Reference
the target server in the "Default Target Endpoint"
- <
Server name="TargetServerName" />
- Set
Target Path
- Each
resource path should define the target path.
- If the
target path changes per environment, then use the KVM to store the target
path
- If it
does not change per environment, then use an AssignMessage or Javascript
policy to set the target path
- Refer to
"AssignMessage.SetGetResourceTargetPath" for how to set a value
for the "flow.request.targetPath" variable
- Use KVM
if needed
- Create
KVM for environment in the Management UI or API
- Refer to
the "KeyValueMap.GetConfigSettings" policy for KVM reference
- Modify
the mapIdentifier="APIConfig" setting in the policy. This should
be the name of the KVM you created.
- Set
VirtualHost in proxy default to match the correct VirtualHost.
- This
should be an https host. The default https host is "secure". If
you created a custom VirtualHost, use that name instead.
- Enhance
Error Handling if needed
- If you
have added new policies or need to handle extra types of Faults, refer to
the FaultRules and DefaultFaultRule flow in the default proxy endpoint
- Edit the
"FaultRules.DefaultErrorResponse" to change the format of the
error response
- Leverage
Custom Analytics if required
- Reference
the "Stats.RecordCustomAnalytics" policy
- Add
additional fields to track
