Best Practices

We want you to have a great experience building on the Regulatory and Licensing - API integration platform. Here are our best tips!

Ensuring Secure Connections with TLS 1.3

Our API supports only TLS 1.3 to ensure the highest level of security and performance for your integrations. By using TLS 1.3, we provide stronger encryption, improved connection speeds, and protection against vulnerabilities found in older versions of the protocol. This ensures that all data transmitted between your systems and our API remains secure and compliant with modern security standards.

Send Valid Payloads

All payloads sent to our platform must be valid JSON and UTF-8 encoded with Content-Type: application/json. Ensure that your payloads adhere to the schema requirements provided in the API documentation.

Avoid Validation on New Payload Fields

Our platform will provide notifications of planned breaking changes to existing fields; however, we may add new fields to the payload at any time. Avoid strict validation that rejects unknown fields to ensure forward compatibility.

Handle Rate Limiting Gracefully

We enforce rate limits to ensure fairness and performance across our platform. When you reach the limit, you’ll receive a 429 Too Many Requests response with information about retry windows. Please implement retry mechanisms with exponential backoff to avoid overloading the platform.

Secure API with OAuth2 Authentication

Our platform uses OAuth2 for authentication and authorization. You will be provided with a clientId and clientSecret to access the platform’s secure endpoints. To authenticate, call the /authenticate endpoint using your clientId and clientSecret to obtain a JWT bearer token. The token will expire in 1 hour, so ensure that your application handles this by requesting a new token from the API once the current token expires.

Handle Errors Gracefully

Ensure you are handling error responses gracefully in your application. We use standard HTTP status codes such as 400 Bad Request, 401 Unauthorized, and 500 Internal Server Error. Always parse the error body for detailed error messages and provide meaningful feedback to end users. Consider implementing retry logic for transient errors like 503 Service Unavailable.

Use Test Environment for Pre-Production

We provide a sandbox environment for testing and validating your integration before moving to production. Always test your integration thoroughly in the sandbox environment to avoid any disruptions in the production environment. The sandbox environment simulates real-world responses but may have limitations in terms of real-world data and rate limits.

Keep Your API Client Updated

Our API evolves over time with new features and enhancements. Stay updated with the latest version of our API SDKs, libraries, and documentation to ensure compatibility with new functionality and security patches.

Document Your Integration

As you build your integration, maintain internal documentation for how your system interacts with the API. This is essential for long-term maintenance, debugging, and onboarding new developers. Include details such as API endpoints used, data mappings, and error handling procedures.

Provide Descriptive User-Agent Strings

Including a descriptive User-Agent header with your requests helps us identify and support your integration better. Use the User-Agent header to describe your application, including version numbers, so we can tailor support and troubleshooting for your needs.

Example:

User-Agent: MyApp/1.0 (Platform Integration)

Handle Time zones Consistently

All timestamps returned by our API are in UTC by default. Ensure your application consistently handles time zones to avoid discrepancies in time-sensitive data. If you need localized time zones, adjust the timestamps appropriately on the client side.

By following these best practices, you can ensure a smooth, secure, and efficient integration with our platform. If you have any questions or need further support, our technical support team is here to help.

Additional Tips

Keep Your Access Keys and Secrets Secure: Do not expose your API keys or secrets in public repositories or client-side code. Use environment variables or secure vaults to manage sensitive credentials.
Respect API Deprecation Notices: If we announce a deprecated version of the API, ensure you transition to the new version before the deprecation timeline ends to avoid service disruption.