Skip to main content

API 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​

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​

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 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.