Best Practices

This section provides a set of standards that can be followed as best practices in terms of design, configuring, monitoring, and debugging while developing API proxies. The data provided in this section is a collective contribution of developers who use Fiorano API Management extensively for developing API programs.

Version Control

• Include a Version Number in the API Proxy path to keep track of Project changes while updating or upgrading a project.
• Provide a higher version number if there is a major change in the API Policy Configuration. For example, 1.0 to 1.1 or 2.0.
• Retain the older projects in the Version Control System such as Subversion (Svn) and Git. 
• Change the status of the older versions of a project to DEPRECATED/RETIRED.

Reference

Overview

Documentation

Provide proper documentation for every project to eliminate ambiguity. For example, provide adequate values for Short Description and Long Description as well as Input Sample and Output Sample.

Targets

• If there are multiple backend services, define all of them as targets and configure Load Balancing.

• Configure Failover target as an internal service where all the failed requests will be logged onto a database/file.

  • Use context variable target.failover.occurred in the flow to identify the failed requests and prepare an appropriate response to the client.

    

    target.failover.occurred variable will be true if the request hits the failover target.

• Set context variable target.id as FIORANO_NO_TARGET to skip the target invocation.
• Make use of the Enable Retries and the Retry Count properties to handle short-term network fluctuations.
• Provide appropriate values for the Request Timeout and the Connection Timeout properties to reduce response delays in case of target outage.

Reference

Targets

Resources

• Define a resource with base path "/" so that undefined request paths will be responded with proper error message.

  

  Keep this dummy resource at the end of all resources.

• To pass through all the resource paths, enable the Forward Base Path To Target property.
• If a request is qualified for multiple resources, the first resource in the list will be invoked.

Reference

Resources

Policies

• Apply Security policies in the Proxy_Request scope or before the business logic policies.
• If the backend target provides the same response as that for an input, then use the Cache policies.
• Handle all the exceptions in JAVA callout policy to avoid sleep calls in the Java code.

Debugging and Troubleshooting

• After configuring the API Project, debug the policies to verify the responses and to fix runtime API issues.
• If there are any exceptions while applying the policies, the details of the error stack trace will be logged and the same can be viewed from the Logs tab in the Administration section.
• The number of error transactions can be checked in the Analytics view.

Error Handling

• Use the Build Message policy in the POLICY ERROR scope to create an appropriate error message that suggests a solution to the error condition.
• The Context Variables error.occured will be true if an error occurs in the flow.
• Context variable error.type indicates an error occurred in the target, cache or in a policy that can be identified with context variable values "target", "cache" and "policy" respectively.
• Context variable error.policy.name contains the policy instance name referring to the policy which invoked the error.