Best practices

This guide is a work in progress and is not currently complete.

Feel free to contact us to propose topics that should be covered by this guide.

JSON deserialization

Some JSON libraries fail by default when an unknown property is found on the response during deserialization.

Adding a new field to a response is not considered a breaking change and can be done at any time, so it’s important to configure the JSON library to not fail on unknown properties.

Jackson 2 (Java)

The ObjectMapper instances created by the Java library Jackson 2 must be configured to not fail on unknown properties. See the example below.

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;

public class ObjectMapperExample {

    public ObjectMapper getObjectMapper() {
        ObjectMapper objectMapper = new ObjectMapper();
        objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        return objectMapper;
    }
}