Versioning

The major version is in the path: https://api.agoo.ardent.africa/v1. Within a major version, Agoo only makes changes that a well-behaved integration can ignore. Anything that could break one waits for a new major version, which runs alongside the old one for at least 12 months.

During the previewCopy Anchor Link

The API is in preview (version 1.0.0-preview of the contract) while it is built in phase P9. Until general availability, names and fields may still change. Every change, breaking or not, is listed in the changelog. Build against test mode now, and check the changelog before you go live. The guarantees below apply to /v1 from general availability.

Changes that ship without noticeCopy Anchor Link

These are additive. They can arrive at any time, in the API and in webhook payloads:

• new endpoints;
• new optional request fields and query parameters;
• new fields in responses and in event objects;
• new values in enums, such as a new visit status, attendance method or error code;
• new event types;
• new response headers;
• changes to the wording of detail in errors, and to the order of fields in JSON.

Breaking changesCopy Anchor Link

These happen only in a new major version, such as /v2:

• removing or renaming an endpoint, field, parameter or event type;
• changing a field's type or format;
• making an optional request field required, or adding a required one;
• changing what an existing field or status means;
• changing the error code returned for an existing situation;
• changing how events are signed.

When a new major version ships, the old one keeps working, unchanged, for at least 12 months. The changelog announces the date it will be switched off well before then.

Write a tolerant integrationCopy Anchor Link

Your code keeps working through additive changes if you:

• Ignore fields you don't know. If you generate a client from the OpenAPI document, make sure it doesn't reject unknown properties.
• Handle unknown enum values. Treat a status or method you haven't seen as "other": log it and carry on, rather than crashing.
• Ignore unknown event types. Return 2xx for events you don't handle, so Agoo doesn't retry them and eventually disable your endpoint. Better still, subscribe only to the event types you use.
• Branch on error code, never on detail.
• Don't depend on field order or on the exact length of IDs and cursors.

switch (visit.status) {
  case "checked_in":
    showOnSite(visit)
    break
  case "checked_out":
    markLeft(visit)
    break
  default:
    // expected, awaiting_approval, denied, cancelled, no_show, or a status added later
    logUnhandledStatus(visit.status)
}

Webhooks and versionsCopy Anchor Link

Event payloads follow the same rules as the API: an event's data.object has the same shape as the object returned by its endpoint in the same major version. Additive changes can appear in payloads without notice, and breaking changes come only with a new major version.

RelatedCopy Anchor Link