Proxy Development Guidelines

 

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.

1. Name the proxy based on a common proxy naming convention

• Example: {businessunit}-{api-purpose/function}-proxy-v1

2. 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

3. 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

4. Use a KVM for environment specific properties. Proxy should not contain hardcoded urls, credentials or other properties.
5. Use a target server for the backend url

• This is needed for 2-way SSL anyways

6. 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

7. Use spike arrest to protect against DDOS or other bursts of traffic
8. Leverage custom analytics to capture variables
9. Use catchall flow to catch requests for resources that are not defined.
10. Use consistent variable names throughout the proxy. Recommended naming convention:

• flow.request.{variablename}
• flow.kvm.{variablename}

11. Remove unused policies (look for broken chain icon)
12. 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:

1. 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

2. Enforce Spike Arrest policy and the Quota policy
3. Extract the necessary request headers, parameters, path parameters and/or payload data

• Reference the "ExtractVariables.CommonRequestHeaders" policy

4. Fill in the necessary resource flows.

• Replace "getResource" and "postResource" with your resource and verb definitions

5. 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

6. 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" />

7. 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

8. 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.

9. 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.

10. 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

11. Leverage Custom Analytics if required

• Reference the "Stats.RecordCustomAnalytics" policy
• Add additional fields to track