Overview
The Client Services API endpoints are evolved in place rather than explicitly versioned. This approach means we make changes to existing endpoints over time, subject to the rules outlined below.
Changes fall into two categories:
Non-breaking changes: Changes you should be prepared to handle gracefully.
Breaking changes: Changes that will always be announced in advance.
Because Client Services function as webhooks that you implement, you must understand the exact scope of the payloads. The definitions of "requests" and "responses" are reversed compared to standard API calls:
Requests (Client API Inputs) represent the payloads the Eleos Mobile Platform sends to your web services
Responses (Client API Responses) represent the data your web services return to the Eleos Mobile Platform
Non-Breaking Changes
We may make the following changes at any time without advance notice. Your implementation must process each of these gracefully.
New Endpoints: We may introduce new endpoints at any time, but we disable them by default. Client Service APIs remain inactive until you configure a URL for them in App Manager. You will not experience effects from a new endpoint until you explicitly opt in.
New Request Properties: We may add new properties to existing request bodies (what we send to your web services) at any time.
New Enumeration Values: We may add new values to existing enumerations at any time.
IMPORTANT: Your implementation must silently ignore any unrecognized properties. This practice ensures compatibility with new additions and allows you to begin using new properties on your own schedule.
WARNING: Your implementation must process unrecognized enumeration values without errors. Failing to handle these properly will cause parsing errors and unexpected behavior in the mobile app when we introduce new values.
Breaking Changes
We consider the following changes breaking. If any become necessary, we will announce them in advance to provide you time to update your web services accordingly.
Response property made required: An existing optional property returned by your web services becomes required by the Eleos Mobile Platform.
Response property removed: The Eleos Mobile Platform validation rejects unrecognized response properties as an error, making removals breaking.
Enumeration value removed: We remove an accepted value from a response property definition.
Required request property removed: We remove a property marked as required in the documentation from the request (what we send to you). You can always rely on required properties being present.
NOTE: We may deprecate a property and remove it from documentation while still accepting it in validation to avoid disrupting existing integrations.
Breaking changes will always be communicated ahead of time. Subscribe to our release notes to stay informed and plan updates to your web services accordingly.