Take an HTTP API endpoint which spits out the following response model:

    "type": "Dog",
    "name": "Jessi",

The type field has been described in the documentation as being one of Dog, Cator Fish.

Would adding a new option,say Rat, be considered a breaking API change?

Is adding an option to a finite list (which a developer may switch on) considered an extension or a modifications to an API?

2 Answers 2


If the documentation described this field as being one of Dog, Cat, or Fish, then yes, adding another type changes the interface in a backwards-incompatible way. It is entirely conceivable that a consumer of your API has written specific code to deal with dogs and cats differently than with fish. Given an unknown type, that consumer wouldn't know what to do with your response. But this depends very much on what these placeholder types “Cat” and “Fish” represent in your actual problem domain…

If changes to the list of possible types is frequent, or if the list is not finite, then documenting this as such is sensible. Depending on your use cases, it might be good to expose a list of all possible types as an endpoint in your API – that way it's clear you can add or remove types without having to update the API version. However, the more dynamic your types are, the harder it becomes for API consumers to do something type-specific. Whether extensibility or ease of use is more important depends on your use cases and your problem domain.

  • Fantastic answer - thanks. What if the documentation detailed the options in some table titled with "the following table describes the animals currently supported by the API." Does this not indicate that the options could be expanded upon?
    – Dave New
    Feb 3, 2017 at 14:57
  • 1
    @davenewza That's probably a good idea but I would be more explicit. Don't just indicate what you mean – say it directly! I'd try to set clear expectations and offer a stability guarantee in the docs for that endpoint, something like: “The following table lists the currently supported animals, though we may add or remove supported animals in the future. When that happens, we'll update the minor version number of the API.”
    – amon
    Feb 3, 2017 at 15:11
  • Executable specification >>> documented specification >>> undocumented specification. Feb 3, 2017 at 16:01

It would only be breaking if "Rat" could be returned from existing operations.

If existing operations cannot return "Rat" then adding this new option would have no effect.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.