Official REST API policy

Purpose

This API policy outlines the responsibilities and expectations for both our organization and our customers or partners when interacting with iGrafx REST APIs. Our primary goal is to ensure that our APIs are reliable, consistent, and as backwards compatible as possible. We aim to provide stable interfaces that allow your applications and integrations to continue functioning seamlessly across API versions, even as we introduce new features and enhancements.

However, it is important to recognize that certain changes, especially those addressing security concerns or correcting incorrect behaviors, may require adjustments on your end. While we strive to maintain compatibility, there may be situations where breaking changes are necessary, and in such cases, we commit to clear documentation and, where possible, a deprecation period.

As a customer or partner, it is your responsibility to design your API interactions in an industry-standard manner, which anticipates the potential of additional properties being returned in a payload. By doing so, your applications will remain robust and adaptable to the evolution of our API offerings.

iGrafx Best Practices

Backward Compatibility

iGrafx will strive to maintain backward compatibility for REST resources, inputs, and outputs wherever possible. This primarily includes property name, nesting and type consistency. This ensures that programs developed using a specific version of the API will continue to function without modification when used with future versions.

Handling Unknown Properties

The REST API is designed to ignore any unknown properties within JSON objects and any unrecognized query parameters in URLs that you are submitting. This approach minimizes disruption to API integrations as new properties or parameters are introduced.

Behavioral Changes

The behavior of an API may change without prior notice if the existing behavior is incorrect or poses a security risk. Such changes are necessary to maintain the integrity and security of the platform.

Breaking Changes

In some cases, breaking changes to the API may be unavoidable, such as when a platform feature undergoes significant modifications that render an older API obsolete. Any such breaking changes will be clearly documented at the time of release. Whenever feasible, APIs will first be marked as deprecated before a breaking change is implemented.

No advance notification for property additions

Customers will not receive advance notifications when new properties are added to API payloads. It is expected that API consumers will design their integrations to accommodate these additions without requiring immediate updates to their integrations as new properties get introduced on the iGrafx side (see below).

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
}