Versioning of APIs is a decent practice. Versioning helps make your API more adaptable and versatile to changes while keeping the functionality intact. It also helps you manage changes to the code better and more easily revert back to old code if the new code causes problems. You ought to have an alternate form of your RESTful API with each significant delivery.

Versioning an API  permits us to help diverse usefulness for a similar asset.

For instance, consider a blog application that offers an API for dealing with its centre information, for example, clients, blog entries, classes, and so on. Suppose the principal cycle has an endpoint that makes a client with the accompanying information:

name, email, and a secret key. A half-year later, we conclude that each record presently should incorporate a job (administrator, manager, creator, and so on). What would it be advisable for us to do with the current API?

We essentially have two options:

1. Update the user API to require a role with every request.
2. At the same time uphold the old and new client APIs.

There are three primary ways to implement API versioning:

(1) URL

This is the easiest and most common way and can be achieved using either the path:

POST : Http ://localhost:8080 /v2/ielts_new/users

Or by using query parameters:

POST:  /blog/users?version=2

URLs are convenient because they’re a required part of every request, so your consumers have to deal with it. Most frameworks log URLs with every request, so it’s easy to trace which consumers are using which versions.

It’s best for the Client. 

Note :  It disrupts the RESTful compliance: URIs should represent resources and not versions (one URI = one resource/resource version).

(2) Headers

You can do this with a custom header name that your services understand:

API-Version: 2

Using headers for versioning is more in line with RESTful practices. After all, the URL should represent the resource, not some version of it. Additionally, headers are already great at passing what is essentially metadata between clients and servers, so adding in version seems like a good fit.

Note: Headers are cumbersome to work within some frameworks, more difficult to test, and not feasible to log for every request. Some internet proxies may remove unknown headers, meaning we’d lose our custom header before it reaches the service. 

(3) Message body 

We could wrap the message body with some metadata that includes the version:

{

     metadata: {

    version: 2

  },

  message: {

    name: “John Doe”,

    email: “john@stackoverflow.com”,

    password: “P@assword123”,

    role: “editor”

  }

}

From a RESTful perspective, this violates the idea that message bodies are representations of resources, not a version of the resource. We also have to wrap all our domain objects in a common wrapper class, which doesn’t feel great—if that wrapper class ever needs to change, all of our APIs potentially have to change with it.

Breaking Changes

Examples:

• Delete path(URL changes)
• Rename path operationId
• Delete/Rename parameters
• Add a constraint on a parameter (like isRequired)
• Modify a response item

Smooth Changes

Examples:

• Add a path
• Add a param
• Add response item
• Add/Update descriptions

Note : consider using something beyond a simple counting scheme (v1, v2, etc). You can provide some more context to your users by using a date format (i.e. “201911”) or even semantic versioning.