CODEWITHSUNDEEP
restapi-design
Victor Maricato
Victor Maricato

Reputation: 812

Making an endpoint's return optional through query string: how to choose default behaviour?

An API X, until day D (e.g.: 2021-12-30), returns two elements: (A, B), e.g.:

{
"A": 10,
"B": 50
}

However, computing B part of the return is expensive, so it was decided to make B optional. A client application should request B's computation through a query string (e.g.: my-endpoint.com/something?computeB=True)

Yet, until day D, all client applications assumed B was returned and did not concern about B's computation complexity.

Therefore, not returning B would break a contract with previously existing applications. These applications may not really require B but it was convenient to use when available.

So I'd like to ask:

Regarding best practices of a RESTful API, should I break the existing contract in favor of optimization or should I make computeB default value to True?

Upvotes: 0

Views: 37

Answers (1)

njzk2
njzk2

Reputation: 39406

should I break the existing contract

No, by definition.

If you want to change the default behaviour, create a new version of your API.

Regardless, you can encourage your users to switch to not requesting B.

Either by deprecating the current version (with sufficient notification), or by making it more costly (which can mean slow, less efficient, or just more expensive) to request B (again, with sufficient notification ahead of time)

Upvotes: 2

Related Questions