You're putting the burden of learning implementation details of your system onto your customers. That won't be comfortable for either them or you. Should you need to deprecate a method you'll never be able to remove it. So be prepared to write a lot of { "Error": "ErrorCodeThatOnlyMakesSenseInTheContextOfThisAPI", "Description": "DEPRECATED" }