Versioning and Breaking Changes

Occasionally Mobiledock will deprecate and remove API functionality as we streamline our API product, replacing overlapping or superseded operations with a single supported way of doing the same thing. When that happens we give notice, document the replacement, and keep the old behaviour running long enough for you to move across.

Most of what we ship is additive and needs nothing from you. This page sets out where the line sits, so you know which changes your integration has to tolerate and which ones we owe you notice for.

Changes we can make at any time

These are additive. We ship them without notice, and will not affect existing integrations.

• New operations
• New fields in responses
• New optional parameters and optional request fields
• New values in an enum
• New webhook event types, and new fields in existing webhook payloads
• New error codes

To ensure your integrations remain compatible with these types of changes, we recommend the following to those integrating with Mobiledock:

• Ignore response fields you do not recognise rather than failing to parse.
• Handle an unknown enum value by falling back to a default instead of throwing.
• Do not rely on the order of fields, or of list items where we have not documented a sort.

Changes we treat as breaking

• Removing or renaming an operation, a field, or an accepted value
• Adding a required parameter, or making an existing optional one required
• Changing the type of an existing field, or no longer guaranteeing that it is present
• Changing what an existing field or status value means
• Tightening validation so a request we used to accept is now rejected
• Removing a webhook event type, or removing a field from its payload

We do not make these changes to an operation you are already calling. Where we need the new behaviour, we add it alongside the old one, usually as a new REST endpoint, and the operation you integrated against keeps running.

Notice and support windows

When we deprecate API functionality your integration uses, we will:

• Email the technical contacts registered against affected integrations at least 30 days before any scheduled deprecated behaviour changes in Production environments
• Keep the previous version available to affected integrations for at least 6 months after any scheduled deprecated behaviour changes in Production environments

If we have no working service update contacts for your integration, we cannot warn you. Keep your contacts up to date.

The commitments above do not apply to changes required to address a security vulnerability, a legal or regulatory obligation, or a product defect. For these, we will notify affected customers as soon as practicable.

If you have questions about a specific change, or about a deprecation that affects you, go to assistance@mobiledock.com.