-1

I am trying to refactor some older APIs, by changing response codes. But the client which is calling these APIs is using these response codes in their logic. So how to change response codes of APIs without breaking the client, and without API versioning?

I know that we can version APIs, but for that we have to communicate to clients so that they can change their code accordingly. So is there a generic way to do this?

Manoj Majumdar
  • 505
  • 1
  • 4
  • 23
  • You should not retroactively change APIs, and response codes are part of the API. Any change you make is a new version of the API, whether or not your API actually tells its clients what version it is implementing. – Arfur Narf Mar 31 '23 at 12:31
  • What you are describing is a _Behavioral Breaking Change_. Clients are dependent upon the existing behavior and changing that is likely to break them. To change it, you'll have add new resources and paths or have some form of versioning. When done correctly, version compatibility with existing clients is possible without them having to change. – Chris Martinez Mar 31 '23 at 17:54
  • so what i understand here is , whenever we change the response codes, we have to make a new version of the Api, I was hoping for a generic way in which we could always change response codes by keeping the meaning of HTTP status codes. For example, we decide to keep 200 for empty responses instead of 204, but the client has already used 204 in their code. – Manoj Majumdar Apr 01 '23 at 05:25
  • @ArfurNarf Thanks for your answer, although it mainly focuses of api versioning , but what i need is to avoid versioning – Manoj Majumdar Apr 01 '23 at 05:36
  • Your choices: (1) no incompatible changes in the interface, (2) break client code, (3) something equivalent to versioning. Since you originally said you want to make incompatible changes, that leaves the other two choices. There's no magic pixie dust. – Arfur Narf Apr 01 '23 at 12:39

1 Answers1

1

One way is to make the client tell you what version of the API it is coded to, and have the server adapt accordingly.

Back-compatibility can be handled: if the client does not include the 'version indicator' in its request (as existing clients will not be doing) then that means the oldest version.

You're then going to have to have (at least) two sets of response codes, the ones in use today and the ones you want to move to. That's the price of compatibility.

Depending on your user base, you can deprecate and eventually eliminate the older API. Typically that is an announcement that 'the older API will be removed in version x.y'.

Arfur Narf
  • 392
  • 1
  • 5
  • Small point of order, it should simply be _capability_. The two implementations live side-by-side, but the overall approach is sound. The original implementation has some logical version that was never formalized. For example, it might be called _V1_, even if that doesn't manifest in the API. Allowing clients to omit the API version is how they opt into that version without them breaking. It's also a good idea to allow old clients to explicitly specify an API version without having to update. In other words, `/resource` and `/resource?api-version=1.0` should be equivalent. – Chris Martinez Mar 31 '23 at 17:59
  • @ChrisMartinez your suggestion is quite clever, this query parameter thing can be done to avoid changes at the client side everytime. – Manoj Majumdar Apr 01 '23 at 05:27
  • I note this is exactly 'versioning', and what I had in mind (assuming you're using an API based on HTTP, which was nowhere stated). Thanks to @ChrisMartinez for the clarification. – Arfur Narf Apr 01 '23 at 12:41