Skip to main content

Build a resilient API integration

Design your REST API client so it keeps working as the API evolves. The REST API compatibility policy describes what iGrafx keeps stable; the practices below are what your integration should do in return.

Prerequisites​

Steps​

  1. Call endpoints exactly as documented. The compatibility policy covers the endpoint URLs and request and response formats as published. A variation that happens to work — for example, an endpoint URL with an extra trailing slash — isn't covered and can start returning errors in a later version.

  2. Ignore property order. Read JSON by property name, not position. Treat these two responses as identical:

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

    Order within an array still matters where the array is ordered — preserve it there.

  3. Tolerate new properties. iGrafx can add properties to a response without notice. Your client should keep working when it sees a field it doesn't recognize — for example, if a later version adds enabled:

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

  4. Retry transient failures. Network blips, DNS failures, and brief unavailability happen. Retry with a delay that grows after each attempt (exponential backoff), and add a little randomness (jitter) so many clients don't retry in lockstep. Limit retries to repeatable requests such as GET and PUT to avoid unintended side effects.

  5. Validate and sanitize input and output. Check data before you send it, and check and sanitize what you get back. This guards against malformed data, unexpected changes, and injection risks.