{"id":6227,"date":"2020-09-30T13:12:43","date_gmt":"2020-09-30T07:42:43","guid":{"rendered":"https:\/\/www.innovationm.com\/blog\/?p=6227"},"modified":"2020-09-30T13:12:43","modified_gmt":"2020-09-30T07:42:43","slug":"versioning-your-api","status":"publish","type":"post","link":"https:\/\/www.innovationm.com\/blog\/versioning-your-api\/","title":{"rendered":"Versioning your API"},"content":{"rendered":"

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 <\/span>back <\/span>to old code if the new code causes problems. <\/span>You ought to have an alternate form of your RESTful API with each significant delivery.<\/p>\n

Versioning an API \u00a0<\/span>permits us to help diverse usefulness for a similar asset.<\/p>\n

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:<\/p>\n

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?<\/p>\n

We essentially have two options:<\/span><\/p>\n

    \n
  1. Update the user API to require a role with every request.<\/span><\/li>\n
  2. At the same time uphold the old and new client APIs.<\/li>\n<\/ol>\n

    There are three primary ways to implement API versioning:<\/span><\/p>\n

    (1) URL<\/b><\/p>\n

    This is the easiest and most common way and can be achieved using either the path:<\/span><\/p>\n

    POST : Http<\/span>\u00a0:\/\/localhost:8080 \/v2\/ielts_new\/users<\/span><\/p>\n

    Or by using query parameters:<\/span><\/p>\n

    POST:\u00a0 <\/span>\/blog\/users?version=2<\/span><\/p>\n

    URLs are convenient because they\u2019re a required part of every request, so your consumers have to deal with it. Most frameworks log URLs with every request, so it\u2019s easy to trace which consumers are using which versions.<\/span><\/p>\n

    It\u2019s best for <\/span>the <\/span>Client.\u00a0<\/span><\/p>\n

    Note<\/span> :\u00a0 <\/span>It disrupts the RESTful compliance: URIs should represent resources and not <\/span>versions<\/b> (one URI = one resource\/resource <\/span>version<\/b>).<\/span><\/p>\n

    (2) Headers<\/b><\/h4>\n

    You can do this with a custom header name that your services understand:<\/span><\/p>\n

    API-Version: 2<\/span><\/p>\n

    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.<\/span><\/p>\n

    Note<\/b>: Headers are cumbersome to work <\/span>within<\/span>\u00a0some frameworks, more difficult to test, and not feasible to log for every request. Some internet proxies may remove unknown headers, meaning we\u2019d lose our custom header before it reaches the service.\u00a0<\/span><\/p>\n

    (3) Message body\u00a0<\/b><\/h4>\n

    We could wrap the message body with some metadata that includes the version:<\/span><\/p>\n

    {\r\n\r\n\u00a0\u00a0\u00a0\u00a0\u00a0metadata: {\r\n\r\n\u00a0\u00a0\u00a0\u00a0version: 2\r\n\r\n\u00a0\u00a0},\r\n\r\n\u00a0\u00a0message: {\r\n\r\n\u00a0\u00a0\u00a0\u00a0name: \u201cJohn Doe\u201d,\r\n\r\n\u00a0\u00a0\u00a0\u00a0email: \u201cjohn@stackoverflow.com\u201d,\r\n\r\n\u00a0\u00a0\u00a0\u00a0password: \u201cP@assword123\u201d,\r\n\r\n\u00a0\u00a0\u00a0\u00a0role: \u201ceditor\u201d\r\n\r\n\u00a0\u00a0}\r\n\r\n}<\/pre>\n
    From a RESTful perspective, this violates the idea that message bodies are representations of resources, not a version<\/span>\u00a0of the resource. We also have to wrap all our domain objects in a common wrapper class, which doesn\u2019t feel great\u2014if that wrapper class ever needs to change, all of our APIs potentially have to change with it.<\/span><\/p>\n
    Breaking Changes<\/b><\/h3>\n
    Examples:<\/span><\/p>\n