Breaking changes - API

When Moov manages API changes and releases, it’s crucial for us to distinguish between breaking and non-breaking changes to ensure smooth transitions and maintain your functionality.

Moov reserves the right to make changes to our API at any time. Breaking changes disrupt existing integrations and require immediate updates to mitigate errors. Non-breaking changes enhance or extend the API without affecting current operations. Certain changes may straddle the line, making it essential to consider the context and usage patterns. This page covers various API change scenarios, identifying which changes are breaking and non-breaking.

Moov will communicate all breaking changes directly, in an appropriate time frame for customers to update their integrations accordingly. Breaking changes will also be announced in our changelog (subscribe for notifications).

Note that “field” can refer to a field in a request body, response body, query parameter, header value, or any other variable or value used by the API.

Breaking changes

The following list has been established as breaking changes and will require action to remedy.

1. Removing an existing field

Example: Removing the lastName field from the user profile API.

Outcome: Integrations that depend on this field will encounter errors or incomplete data.

2. Changing the data type of a field

Example: Changing the id field from a string to an integer.

Outcome: Integrations expecting a string may fail to parse the new integer value.

3. Changing the structure of the response

Example: Modifying the response structure from a flat JSON to a nested JSON.

Outcome: Integrations that parse the response based on the old structure must adapt to the new structure.

4. Removing an endpoint

Example: Removing the GET /users/{userID}/profile endpoint.

Outcome: Integrations that rely on this endpoint will no longer be able to retrieve user profiles.

5. Changing endpoint URLs

Example: Changing the endpoint URL from /user to /profile/user.

Outcome: Integrations will break if they have not been updated with a call to the new URL.

6. Modifying required fields in requests

Example: Making the email field required in a request where it was previously optional, or adding a new required field.

Outcome: Requests will fail if the modified field is not provided.

7. Changing HTTP methods

Example: Changing the HTTP method from POST to PUT for creating a new resource.

Outcome: Request methods must be updated accordingly.

8. Changing default values

Example: Changing the default value of a sortOrder field from ASC to DESC.

Outcome: The change alters the default behavior of the sort. If the integration relied on the previous default sorting behavior, it will need to accommodate this change, otherwise it can be ignored.

9. Changing date formats

Example: Changing date format from MM-DD-YYYY to YYYY-MM-DD.

Outcome: Date parsing must adapt to the new format.

10. Adding authentication requirements

Example: Requiring an API key for an endpoint that previously did not need authentication.

Outcome: New authentication mechanisms must be implemented.

11. Changing field names

Example: Renaming username to user_name.

Outcome: References must update to the new field.

12. Changing pagination logic

Example: Switching from page-based to cursor-based pagination.

Outcome: Changes are required for handling new pagination logic.

13. Changing a field’s valid values

Example: Removing a previously valid enum value.

Outcome: Changes are required to use a different value.

14. Adding new fields to responses that require interaction

Example: Adding a disabledOn timestamp to the user profile response.

Outcome: Generally considered non-breaking, however in this case it could be considered breaking as it states this model is disabled and non-interactable.

15. Adding a new enum value to field set - Moov set, integration read

Example: Adding a DISABLED status to an existing status enum.

Outcome: Integrations aren’t set up to handle new values. A new enum value will fall through a catch all error.

16. Bug fixes resulting in different status codes

Example: Changing an HTTP response code from 404 Not Found to 409 Conflict.

Outcome: Integration expects a 404 for the specific error case but is getting back a 409. Integration must update to handle this new response code.

Non-breaking changes

The following list has been established as non-breaking changes for integrations that adhere to industry standards.

1. Adding a new optional field to a response

Example: Adding an optional middleName field to the user profile response that the integration may or may not return.

Outcome: Integrations should not be affected by this change. However, this action may result in a breaking change if response fields are strictly validated.

2. Adding a new informational field to a response

Example: Adding a createdAt or updatedOn timestamp to the user profile response that will always be returned.

Outcome: Integrations should not be affected by this change. However, this action may result in a breaking change if response fields are strictly validated.

3. Adding new endpoints

Example: Adding a new endpoint GET /users/{userID}/friends.

Outcome: Integrations are not affected by new endpoints.

4. Deprecating an endpoint (with adequate notice)

Example: Marking GET /users/{userID}/profile as deprecated but still functional.

Outcome: As long as the endpoint continues to function and integrations have time to update, this is a non-breaking change.

5. Enhancing performance or fixing non-behavioral bugs

Example: Improving response time or fixing a typo in the documentation.

Outcome: These changes do not affect the API’s interface or expected behavior.

6. Adding new response headers

Example: Including a new header X-Request-ID in responses.

Outcome: As long as existing headers remain unchanged, this is a non-breaking change.

7. New enum value to field set - client set, Moov read

Example: Adding a NEW_FEATURE status to an existing action enum.

Outcome: Fields set and requested by the integration owner should not break since its return is expected.

8. Bug fixes resulting in different status codes - generic to specific

Example: Changing an HTTP response code from 409 Conflict to 500 Internal Server Error.

Outcome: Moov considers this non-breaking if a generic error status code of 500 or 400 is changed to a status code that’s already defined by the API.

9. Consistent array ordering without explicit ordering specified

Example: Returning an array of ['b', 'a'] without specifying it must be alphabetical via a query argument.

Outcome: An item in an array doesn’t care about order.

10. Consistent map ordering

Example: Returning an map of {"b": true, "a": true}.

Outcome: All lookups of the value are via the key.

Summary Beta