Best Practices

This section provides a set of standards that can be followed as best practices to be followed in terms of design, configuring, monitoring, and debugging while developing API proxies. The data provided is a collective contribution of developers who extensively use Fiorano API Management 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 the project.
• Provide a higher version number if there is a major change in the API Policy Configurations. For example, 1.0 to 1.1 or 2.0.
• Retain the older projects in Version Control system such as svn and git. 
• Change the status of the older versions of the project to DEPRECATED/RETIRED.

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 into a database/file. Use context variable target.failover.occurred in the flow to identify these failed requests and prepare an appropriate response to the client.

  Icon

  Context variable "target.failover.occurred" 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 Enable Retries and Retry Count properties to handle short-term network fluctuations.
• Provide appropriate values for the Request Timeout and Connection Timeout properties to reduce response delays in case of target outage.

Resources

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

  Icon

  Keep this dummy resource at the end of all resources.

• To pass 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.

Policies

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

Debugging and Troubleshooting

• After configuring the API Project, debugging the policies to verify the responses and 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 from the Analytics view.

Error Handling

• Use Build Message policy policy in 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 any error occurs in the flow.
• Context variable error.type indicates whether the error is occurred in the target, cache or in any policy, which can be identified with the 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.