API Best Practices

Following these best practices will help you build integrations that are secure, reliable, and efficient.

Use a Dedicated API User

Create a dedicated API user for each integration instead of sharing the same user across multiple systems.

This allows you to:

• Apply the principle of least privilege.

• Restrict access to only the data required by each integration.

• Audit API activity more effectively.

• Minimise the impact if an API token is compromised.

Grant the Minimum Required Permissions

Assign only the permissions required for the integration to perform its intended tasks.

Avoid granting broad access when a more restrictive API role is sufficient.

Store API Tokens Securely

Treat API tokens as sensitive credentials.

• Store tokens in a secure secret manager or encrypted configuration.

• Never hard-code tokens in source code.

• Never expose tokens in client-side applications.

• Rotate tokens if you suspect they have been compromised.

Handle Errors Gracefully

Your integration should handle API errors appropriately.

• Validate requests before sending them.

• Handle authentication (401) and authorisation (403) errors.

• Respect 429 Too Many Requests responses and the Retry-After header.

• Retry transient failures where appropriate.

Monitor Rate Limits

Monitor the X-RateLimit-Limit and X-RateLimit-Remaining response headers to track your current usage.

As rate limits are shared across your organisation, applications should avoid making unnecessary requests.

Request Only the Data You Need

Where supported:

• Use fields to limit the data returned.

• Apply filters to reduce the number of records.

• Use pagination when retrieving large result sets.

Reducing response sizes improves performance for both your integration and the API.

Cache Data Where Appropriate

Avoid requesting data that changes infrequently.

Caching reference data can significantly reduce API traffic and help avoid reaching rate limits.

Use the Interactive API Reference

Use the interactive API v2 Reference to explore endpoints and validate requests before implementing them in your application.

The interactive documentation allows you to execute requests directly from your browser without requiring an external API client.

Use HTTPS

Always communicate with the API over HTTPS.

Do not transmit API tokens or sensitive data over unsecured connections.

Keep Integrations Up to Date

Monitor release notes and API announcements for new features, enhancements, and deprecations.

Regularly review your integration to ensure it continues to follow current API recommendations.

Use the Sandbox Environment for Development

Develop and test your integration using the sandbox environment before connecting to your production environment.

The sandbox environment allows you to:

• Develop and validate your integration without affecting production data.

• Test API requests and responses using sample data.

• Verify authentication, authorisation, and business logic.

• Experiment with new functionality in a safe environment.

Before deploying your integration to production:

• Verify that all required API endpoints behave as expected.

• Confirm that error handling is implemented correctly.

• Validate that the integration performs as expected under typical workloads.

• Update your application to use the production API endpoint and production API credentials.

Note: Sandbox and production environments use separate API users and API tokens. Credentials created for one environment cannot be used to access the other.