I have a public REST API for creating new business profile records in my system. The request itself looks similar to this:

    "BusinessName" : "AName",
    "CurrencyCode" : "USD"

You can see the CurrencyCode property on the request is set to "USD" and our REST API documentation incorrectly asserts that we support "USD" or "EUR" as values to this property.

Here's the problem, in recent talks with the busisness it became clear that while we may support multiple currency codes in the future today we only support "USD", and on top of that we will never support changing the CurrencyCode on the request since it's a limitation in our industry. Our existing code ignores the value of "CurrencyCode" on the request and hardcodes it to "USD" throughout our system (legacy code).

So due to the fact that we will never support CurrencyCode being passed on the request the decision was made to remove it. So going forward if "CurrencyCode" is provided on the request we will continue to ignore it so the user wont get an error and processing will continue as expected as long as they are passing "USD". If however they coded against our current API documentation and expected that support to be in place then they will encounter problems when their software attempts to use "EUR" for currency code.

Granted today's users of the API do not have any way of using the "Eur" currency code because our applicaiton is ignoring this value. However, I would argue that this is a bug and that the removal of this value without any kind of versioning of the api is a bad practice. I assert this should be considered a breaking change.

So the question, "Is removing the "CurrencyCode" property from the request a breaking change even though we don't support it today(bug) and will never support it in the future?"

  • 1
    A breaking change is any change that will break existing client code. Oct 8, 2015 at 20:31
  • "and on top of that we will never support changing the CurrencyCode on the request since it's a limitation in our industry." What are you going to do if/when Greece leaves the Euro and goes back to the Drachma? Oct 8, 2015 at 22:52
  • It's not that my application wont support currency code in general, it will just never be supported in the request to our api.
    – P. Roe
    Oct 12, 2015 at 21:37

1 Answer 1



If your code ever actually allowed public consumers to set their CurrencyCode to EUR, and now it doesn't, then that is a breaking change since you're changing the semantics. If your code always used USD even if that was a bug, then it is not a breaking change.

But ignoring the input itself and changing the documentation to reflect that is not a breaking change in and of itself.

  • So "Johnny Developer" tells his boss that he's got the currency switching code completed.
    – P. Roe
    Oct 8, 2015 at 21:21
  • @PaulRoe: Yes, and that is the truth until someone tries to use or review that feature and finds that it doesn't actually work. Oct 9, 2015 at 6:42
  • EUR is a documented constant that can be passed as part of the request, how does that qualify as part of the semantics of the endpoint?
    – P. Roe
    Oct 12, 2015 at 22:05
  • 1
    @P.Roe - I'm not sure I understand the question? The semantics of the API call is how it behaves given a set of inputs. If your code takes EUR but does nothing, then you are changing the semantics if it suddenly takes EUR and blows up.
    – Telastyn
    Oct 12, 2015 at 22:43

Your Answer

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

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