1

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

Shazia Tabassum
  • 115
  • 11
  • 3
    If by adding more parameters, you **break** the API contract (e.g. existing callers won't be able to call your API anymore, but will get errors), then you **should absolutely** create a new, separate version – marc_s Sep 15 '21 at 07:00
  • Agreed with @marc_s's reply. If you can add the new params while maintaining backwards compatibility, then you don't need to create a new versioned endpoint. If existing callers will result in an error, then you need a new version. – John Sep 15 '21 at 07:02
  • 1
    New *mandatory* parameters are a break and need a new version. New *optional* parameters could be added, if not setting it, leads to the current behaviour. The same is true for responses. – Oliver Sep 15 '21 at 07:02
  • In my opinion, if you have a public API that people are using already, you must add API versioning but if you(or your team) are the only users that using the API you can break the contracts and add new parameters. so it depends on your use case. – AliReza Sabouri Sep 15 '21 at 07:04

1 Answers1

2

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.

Ron Klein
  • 9,178
  • 9
  • 55
  • 88