Versioning

Every path starts with /api/v1. Within v1, Ele changes the API only by adding to it.

What can change in v1

Ele may, without notice:

• Add new operations.
• Add new optional request fields.
• Add new fields to responses.
• Add new values to enums, such as a new payment status or a new error type.
• Change the wording of message and description text.

Ele does not, within v1:

• Remove an operation or a response field.
• Rename a field, or change its type.
• Make an optional request field required.
• Change what an existing value means.

What your client must do

To keep working as v1 grows:

• Ignore fields you do not know. Do not reject a response because it has extra fields. In Go, encoding/json already ignores them; do not turn on DisallowUnknownFields for responses.
• Handle enum values you do not know. Give every switch on a status, type or kind a default branch that does something sensible, such as showing the item as “other”. This applies to error types too; see Errors.
• Do not depend on field order in objects, or on the order of items unless the operation says how they are sorted.
• Do not branch on message text.

If you generate a client from the spec, choose options that keep these rules, and regenerate it when the spec changes.

Replaced operations

Sometimes a newer operation returns more than an older one. The older one keeps working and stays supported. Its entry in the spec carries x-ele-superseded-by, giving the path of the operation to move to.

Breaking changes

A change that would break a working client goes into a new version, /api/v2. Ele gives notice before it releases a new version.

The changelog

The changelog lists each change to the published API, with its date. Check it when you update your client.