Skip to main content

Backward Compatibility

KICC API services implement backward-compatible changes without incrementing the API version. Changes that break backward compatibility are either released as a new version or provided through a new URI.

Backward-Compatible Changes​

The following changes are considered backward-compatible and will be updated within the existing API version:

  • Adding new API endpoints.
  • Adding new optional parameters to API requests.
  • Changing mandatory parameters to optional parameters in API requests.
  • Adding new parameters to API responses.
  • Adding new Enum values.
  • Adding new error codes or modifying error messages.

Non-Backward-Compatible Changes​

The following changes are considered breaking changes and will involve a version increment or a new URI:

  • Removing existing API endpoints.
  • Adding new mandatory parameters to API requests.
  • Changing optional parameters to mandatory parameters in API requests.
  • Deleting mandatory parameters from API responses.
  • Changing data types of request or response fields.

Client Compatibility Implementation Guide​

To ensure that your system remains unaffected by API updates (such as the addition of new fields), clients must be configured to ignore unknown properties.

For example, in Java (Jackson Library), the ObjectMapper by default fails when it encounters a field in the API response that is not defined in your local DTO. To prevent errors, apply the following configuration:

Java ObjectMapper Configuration
// Jackson 1.9 and earlier
objectMapper.configure(DeserializationConfig.Feature.FAIL_ON_UNKNOWN_PROPERTIES, false);

// Jackson 2.0 and later
objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);