Deprecating Public API

May 24, 2021

JavaScript
Web development

Lately I have encountered a problem I haven’t put too much thought into before: how to replace API in the JavaScript library. What to do when the API changes the signature? And when there’s almost the same API that will replace it in few versions? Here’s my take on the few possible scenarios.

Deprecation

Deprecating something means that the piece of software marked as “deprecated” is already replaced by some better version of it, or by a method that does almost the same job. It is an indication for the developers using your software to avoid calling the API as in few versions it might become broken or deleted from the library altogether. You can mark some API as deprecated to provide a transition period for the customer and let them some time to dapt their software. It’s basically saying “No need to rush, you still have the time, but here’s the thing that you SHOULD be using ASAP”.

When you spot a piece of code that absolutely has no place in the library, you get the temptation to delete it straight away. It is not a good practice, in my opinion. It puts the load of adaptation on the shoulders of third party devs using the package. They’re obliged to change their code as soon as they update your software. Sure, you need to keep in mind that in few versions you need to delete the API, note it somewhere and come back to the task you started few months ago. But I think it’s a part of a service you provide along your package.

How long the transition period should be? It might depend on your company’s rules. It might be, for example, 4 minor releases of the package (following the MAJOR.MINOR.PATH semantic versioning rules). Otherwise, you can wait for the next major version. The frequent updates required by you or your team can also affect the length of the transition period. It really depends on the release cycle and the environment your package is used in.

Parameters in API change

Okay, so let’s say we have a method that fetches us the user details from the server called getUser() that takes user object as a parameter. It is a bad practice, because the developer using your API needs to keep the object somewhere. And anyways, most likely, your API needs one or two fields of that model (say, user ID).

Now, you spot this problem and decide to ease the pain of your fellow devs by changing the signature from getUser(user: object) to getUser(userId: string)`. What to do in this case?

To provide backwards compatibility, you need to make sure that the original method is available in the package. You can create a new API called getUserById. It is a more explicit and clear way to indicate what argument needs to be passed.

The other option is to create a new API with the same name and change the name of the old one to getUserDeprecated() to point out that this piece of software is going away really soon.

API will stop working

In this case you need to make sure that the backend guys (or just backend, if you’re developing the code) is up to date and will keep providing support for the API during the period of deprecation. It is obvious that in this case you need to delete the API completely from your codebase, but the third-party devs should always have the time to adapt and

API name will change

Sometimes you find out that the name of the API is totally not readable and doesn’t explain the purpose of its logic. Or you just want to unify the naming across the library. In all of those cases, the internal logic doesn’t change. You need to inform the users that the name will change and, if possible, remind them about that during all the transition period. In this case the communication is key. Just keep in mind that you can’t over inform the user. They will be the most happy to find the note about the upcoming update every time they open the changelog.

Best practices

We got the ‘why’, now here’s ‘how’. What to do when there are some major API changes coming?

  1. Update @jsdoc comments and add @deprecated tag
  2. Inform about the changes in the Changelog and release notes
  3. Update the documentation and be very clear about the changes and replacements in your API list
  4. Use internal comments in your code. Extremely helpful if you’re not the only one working on the code.
  5. Communicate, communicate, communicate. This is the most important thing to do in the transition period. Both internally - with your colleagues and externally - with your customers. MAKE SURE THEY KNOW.

DISCLAIMER: This list is clearly not exhaustive, it just contains what I think is the basic strategy one can use to move on with the project.