Official REST API policy

Overview

This REST API policy defines the responsibilities and expectations for both iGrafx and our customers or partners when integrating with the iGrafx REST APIs. Our goal is to provide reliable, consistent, and backward-compatible APIs to support seamless integration experiences across versions — even as we introduce new features and enhancements.

While we aim to avoid breaking changes, certain updates (e.g., security fixes or corrections to incorrect behaviors) may require changes to your integration. In such cases, we commit to:

Clearly documenting all breaking changes
Providing deprecation warnings where possible
Minimizing disruption to existing integrations

We also ask our customers and partners to follow industry-standard integration practices, including designing clients that tolerate new or reordered properties. This ensures your applications remain robust as the API evolves.

iGrafx Best Practices

Backward Compatibility

iGrafx will strive to maintain backward compatibility for:

Resource URLs
JSON property names
Property nesting and types

This ensures that applications built on a specific version of the API will continue to function in future versions without modification.

Handling Unknown Properties

Our APIs are designed to:

Ignore unknown JSON properties in requests coming from you
Ignore unrecognized query parameters

This approach allows us to evolve the API without breaking your integration.

Behavioral Changes

Behavior may change without prior notice if existing behavior is:

Incorrect, or
Introduces a security risk

These changes are made to preserve the integrity and security of the platform.

Breaking Changes

When unavoidable, breaking changes will:

Be clearly documented at the time of release
Be preceded by a deprecation period where feasible

Property Additions

New properties may be added to JSON payloads without advance notice. Integrations must be built to handle additional properties gracefully.

Customer and Partner Best Practices

Tolerance against property reordering

Your integrations should treat the following two payloads as identical.

CODE

{
   "username": "joe@example.net",
   "lastLogin": "2024-08-26T12:31:54Z"
}

is to be interpreted the same as

CODE

{
   "lastLogin": "2024-08-26T12:31:54Z",
   "username": "joe@example.net"
}

Property order at any level of the returned JSON object should be ignored. Ordering within array elements however, should remain consistent for all arrays where an order is expected.

Tolerance for additional properties

API consumers must ensure their implementations are tolerant of additional properties that may be added to JSON objects in the REST API in future versions. This includes handling these additional properties gracefully without failure.
If an API currently returns the following payload

CODE

{
   "username": "joe@example.net",
   "lastLogin": "2024-08-26T12:31:54Z"
}

Your integrations should be built in a way that they still function if an additional property is introduced, like below

CODE

{
   "username": "joe@example.net",
   "lastLogin": "2024-08-26T12:31:54Z",
   "enabled": true
}

Implement Retry Logic

API consumers should implement retry logic to gracefully handle transient errors, such as network interruptions, DNS resolution failures, or temporary service unavailability. We recommend retrying failed requests with a short delay that increases after each attempt (a technique known as exponential backoff). Adding some random variation to the delay helps avoid many clients retrying at the same time. Limit retries to safe, repeatable requests like GET or PUT to avoid unintended effects.

Validate and Sanitize Input and Output

Ensure that your integration validates input before sending it to the API, and also checks and sanitizes responses. This helps guard against malformed data, unexpected changes, or injection vulnerabilities that could disrupt your system.