Search code examples
c#apicompatibilityrestapi-versioning

REST API best practice - adding new parameters in request/response of existing API

I am working with .NET 5.0. I have a REST based API currently deployed in production and merchants are already integrated with it. Now there is a requirement that I need to add a few more parameters in request and response as well.

Is that bad practice to add params in existing REST API? Should I introduce a new version, or it is okay to add req/response params in the same version?

EDIT: The additional params are not mandatory

Solution

  • API can be broken in two places: the request (input) and the response (output).

    Request

    If you introduce new input parameters, and you want to keep backward compatibility in your application, then:

    1. your server side should have reasonable default values for missing input parameters
    2. your server side application should keep the same behavior (return the same output, see below) for the input that has these missing values. In other words, the default values (the "fallback") are good enough to return the same results.

    If you don't comply with the above, then your API is broken in terms of input.

    Response

    The response is tricky, because it depends on your consumers, and on the content type of the response.

    If the response's content type is extensible, like JSON or YAML, and your API consumers are aware that new fields can be added to the output in any time, and can be ignored, then your API is backward compatible (namely, not broken) in terms of output.

    However, if your consumers expect a strict schema in the response (a fixed amount of existing fields, for instance), then adding new fields (even if they can be ignored) is not acceptable and thus breaks your API.

    It depends..

    So the answer is: it depends. If new fields are added to the output, then you should either communicate to your consumers about extending the response, or create a new endpoint to your API (/v2/...).

    Also, if there are no reasonable fallback values for input parameters, then this, again, requires a v2 entry point of your API.