# API compatibility (/guides/api-compatibility)



## Backward Compatibility [#backward-compatibility]

Acme strives to maintain backward compatibility for all public API endpoints. This means we adhere
to these principles:

* Existing API endpoints will not be removed without proper deprecation notices
* New required request parameters will not be added to existing endpoints
* Non-optional fields will not be removed from response structures
* Field types and semantics will not be changed

In rare circumstances, we may need to make breaking changes to address critical security issues,
fix significant bugs, or implement essential infrastructure improvements. When these exceptional
situations arise, we will:

* Provide sufficient advance notice
* Clearly document the changes and migration paths
* Offer support during the transition period

## Handling API Changes [#handling-api-changes]

### Recommendations [#recommendations]

* **Be tolerant of unknown fields**: Your client should ignore any fields in responses that it
  doesn't recognize
* **Don't depend on field order**: The order of fields in JSON responses may change
* **Accept new enum values**: Be prepared to handle new values in enumerated fields

### Field Types and Values [#field-types-and-values]

#### Enum Values [#enum-values]

* **Open enums**: Treat all enums as open (non-exhaustive) even if all current values are documented
* **Enum value stability**: Existing enum values will not change meaning, but new values may be
  added
* **Enum deprecation**: Enum values may be deprecated but will continue to be accepted in requests
  during the deprecation period

#### Field Type Considerations [#field-type-considerations]

* **Field value parsing**: Parse field values according to the documented field types. For example,
  do not parse a field value as an integer when the documented type is a string, even if the value
  appears numeric.
* **Set field values of correct type**: Use the correct, documented type for field values in your
  requests. For example, use a string for a field value if the documented field type is a string,
  even if the value appears numeric.