Best Practices

Metadata in requests

• Always include the `X-Client-Name` header in your requests to identify your integration

Authentication

• Use OAuth 2.0 for secure access.
• Store tokens securely and refresh them as needed.
• Implement token expiration handling to avoid unauthorized access.

Rate Limiting

• Implement rate limit handling in your integration.
• Respect the API's rate limits to avoid throttling.
• Use the `Retry-After` header to determine when to retry after hitting a rate limit.

Polling

• Limit the frequency of polling to reasonable intervals to avoid overwhelming the API.
• Use webhooks where possible to receive real-time updates instead of polling.

Webhooks

• Validate incoming webhook requests to ensure they are from a trusted source using the signature provided in the webhook headers.
• Log webhook events for debugging and auditing purposes.
• Ensure idempotency in webhook handlers if the same event is received multiple times.

Logging

• Implement structured logging to capture relevant information about requests and responses.
• Ensure sensitive information is not logged.
• Include the `X-Trace-Id` header in logs to trace requests and aid debugging.

Error Handling

• Implement robust error handling to manage API errors gracefully.
• Log errors with sufficient context to aid in debugging.
• Implement retry mechanisms for failed requests, including exponential backoff strategies.