REST API compatibility policy
This reference states what iGrafx keeps stable across REST API versions, when behavior can change, and how endpoints are deprecated. For the practices your integration should follow in return, see Build a resilient API integration.
Compatibility commitments
| Area | Commitment |
|---|---|
| Resource URLs | Kept stable across versions, so calls built on one version keep working in later ones. |
| JSON property names | Kept stable — existing property names aren't renamed or removed. |
| Property nesting and types | The shape and types of existing properties are kept stable. |
| New properties | New properties may be added to responses without advance notice. Your integration must tolerate properties it doesn't recognize. |
| Unknown properties in your requests | The API ignores JSON properties it doesn't recognize in your requests, and ignores unrecognized query parameters — so the API can evolve without breaking your calls. |
These commitments apply to the endpoint URLs and request and response formats as published in the API documentation. A variation that happens to work — for example, an endpoint URL with an extra trailing slash — isn't covered by the policy and can start returning errors in a later version. Call each endpoint exactly as documented.
When behavior can change
| Situation | What happens |
|---|---|
| A behavior is incorrect or poses a security risk | It may change without prior notice, to keep the platform correct and secure. |
| An unavoidable breaking change | It's documented at the time of release, and preceded by a deprecation period where feasible. |
How endpoints are deprecated
When an endpoint is replaced, the original is marked deprecated in the API documentation (both the embedded docs and https://api.igrafx.com) before it's removed in a later release. Check the API documentation for the current status of any endpoint, and see Deprecated endpoints for known migrations.