Best Practices for Using the Zuora API

The subscription economy is growing.

In order to make the most of your investment, you need to effectively manage the Zuora API.

In this article, we list the best practices for using the API.

Let’s take a look!

Best Practices for Using the Zuora API

The API User role is meant for systems making calls to Zuora and should never be used to log into the UI.

Many API applications require higher permission and have a single user/profile with most of the access.

This increases the scope of access unnecessarily since someone may get unintended access to the API login.

Here’s how you can limit and segment access:

Create a Separate API User for Each Integration

Create an API user for each integration and include it as a managed asset.

This limits access scope within Zuora to that particular application as well as cases such as one system locking another out.

If someone accidentally attempts to log in as the API user, the password expires immediately and the API User gets locked out.

Create Different Profiles for Different Domains

Differentiate the scope that a particular API user can use with profiles.

One way is to create profiles for your organization’s access domains, such as QA, Development, Staging, UAT, and Production.

Separate profiles will enable you to set different white lists.

White List IPs

This helps you control where the API user will be allowed to log in from.

It enables you to avoid accidental logins, logins from systems with expired credentials, as well as malicious attempts.

Ensure Security

All user accounts, especially Admin accounts, should be included in your change control and managed like other critical system assets.

API Timeouts and Performance – With Resolution

Troubleshooting

Determine the type of error and its origin. Don’t rule out the possibility of more than one issue occurring simultaneously.

If there’s more than one issue, troubleshoot each one separately before correlating and identifying a common root cause.

• Timeouts
• Connection Issues
• Latency
• Server-Side Errors
• Client-Side Errors

Timeouts

Find out whether it is the client or server side that is timing out. This can occur due to:

• The connection not being established after ‘n’ number of seconds
• Long lived connections
• No data received after ‘n’ number of milliseconds or seconds
• Custom code to kill or close a connection

Connection Issues

This occurs when a TCP connection cannot be established or is closed unexpectedly by either the client or the server.

It is generally treated as an exception by the client.

The details usually include a stack trace, or other trace information showing where the client code and error originated from.

Here’s how you can get more detail about the nature of the connection issue:

• Enable debug logging to dump the stack trace. Verify that the DNS is resolving correctly:

If tests show that no connection is being established with a host within Zuora’s public IP range, then you have a connection issue.

Check the current publically accessible IPs and ranges. If you do see a connection being made, continue analyzing for other possibilities.

Errors That Return a Code or Message

• HTTP 500: Internal Server Error
• HTTP 429
• HTTP 401: Unauthorized

Resolution: Client-Side

The following issues should be addressed on the client side:

• DNS (failure to resolve Zuora hosts)
• Network latency prior to Akamai or Zuora’s Public IP Ranges
• HTTP 500: Internal Server Error – additional error details in the response

Resolution: Server-Side

For issues not resolvable on the client side, contact Zuora Global Support.

Postman Collection for the Zuora REST API

If you use Postman to test the Zuora REST API, you might have tried importing the Zuora Swagger specification into Postman.

Importing the Zuora Swagger specification gives you a Postman collection that contains each API operation, but you need to make modifications before you can successfully send a request.

For example, you may need to disable the parameters and headers that aren’t required, set the Authorization header, and paste in a request body sample from the API Reference.

To make it easier to test the Zuora REST API, Zuora has created a collection that requires much less tweaking.

To import this collection into Postman, navigate from File > Import, then choose the JSON file that you downloaded.

You’ll then see a collection called Zuora REST API (2018-11-15).

Using Postman

When you use Generate an OAuth token in the collection linked above, Postman saves the generated OAuth token in your active environment.

It then automatically sets the Authorization header when you send other requests. Visit Postman documentation to learn more about environments.

Wrapping Up

In this article, you learnt more about the best practices for using the Zuora API, as well as troubleshooting.

To know more, please write to us at [email protected] and we’ll take it from there.