How Our API Works
The ScaleGrowth API is dynamically generated based on the data model of your platform or solution. This gives you access to a full-featured, RESTful API tailored to your business logic.
Whenever you make changes to your data model – such as adding or removing fields on a listing template, modifying member profile structures, or updating the view modes of Smart Fields – your API is instantly regenerated to reflect those changes. This empowers your team to evolve your platform and extend your API on the fly.
Why the API Is Not Versioned Per Change
Due to the dynamic nature of the ScaleGrowth API, it is not static. However, this does not mean we update the API version every time your data model or the underlying API structure changes.
Instead, we use major versioning. The current version of our API is v1. This version supports the full range of dynamic data model functionality and is designed to evolve without breaking your integrations.
We will only introduce a new major version – such as v2 – if and when we make backwards-incompatible changes to an existing endpoint.
Developer Experience and Error Handling
Our team continuously improves the developer experience based on customer feedback. This includes:
- Clarifying error messages
- Updating HTTP status codes for better specificity
- Providing more granular error details
These improvements do not trigger a new version of the API. Instead, they are part of our ongoing commitment to improving clarity and usability for developers.
One exception to our general error-handling pattern is when you're implementing retry logic for the Synchronous API. When issuing multiple parallel requests, we will return HTTP status code 429 Too Many Requests. The response will also include a JSON payload with a field "status": 429. This combination can be used to implement retry logic with appropriate backoff.
Recommendations for Stable Integration
To ensure a robust and reliable integration, follow these best practices:
- Only consider HTTP status codes in the
200-202range as a successful response. Any response in the4xxor5xxrange should be treated as an error. - Build defensively around error responses. Avoid hardcoding logic based on specific message text or code structure, as these may evolve over time.
- Tailor your retry logic around status code
429for Synchronous API throttling. - Use the Asynchronous API for high-volume or parallel processing. It is designed for efficiency at scale and is the preferred method for batch-style or concurrent workloads.
Our Versioning Philosophy
ScaleGrowth is built around a powerful and flexible architecture that allows your API to evolve alongside your platform. This flexibility is made possible by dynamic API generation, and our versioning approach is designed to support it seamlessly.
We use major versioning. The API version only changes when we introduce a breaking change to an existing endpoint. Changes to your data model or improvements to error messaging do not affect the version number.
This approach ensures long-term stability for your integrations, while giving your team full control over your platform’s structure and capabilities.
Summary
ScaleGrowth uses major versioning for its API, updating only when breaking changes are introduced. Version numbers remain the same when the data model changes or when error handling improves. The Synchronous API emits 429 responses (with a "status": 429 field in the JSON payload) to signal throttling – suitable for implementing retry logic. For high-volume processing, the Asynchronous API is the recommended approach.
