what is the purpose of the extra /v1 in the route api/v1

Question

Why not just make your backend api route start with /api?

Why do we want to have the /v1 bit? Why not just api/? Can you give a concrete example? What are the benefits of either?

Answer 1

One of the major challenges surrounding exposing services is handling updates to the API contract. Clients may not want to update their applications when the API changes, so a versioning strategy becomes crucial. A versioning strategy allows clients to continue using the existing REST API and migrate their applications to the newer API when they are ready.

There are four common ways to version a REST API.

1. Versioning through URI Path http://www.example.com/api/1/products

REST API versioning through the URI path One way to version a REST API is to include the version number in the URI path.

xMatters uses this strategy, and so do DevOps teams at Facebook, Twitter, Airbnb, and many more.

The internal version of the API uses the 1.2.3 format, so it looks as follows:

MAJOR.MINOR.PATCH

Major version: The version used in the URI and denotes breaking changes to the API. Internally, a new major version implies creating a new API and the version number is used to route to the correct host. Minor and Patch versions: These are transparent to the client and used internally for backward-compatible updates. They are usually communicated in change logs to inform clients about a new functionality or a bug fix. This solution often uses URI routing to point to a specific version of the API. Because cache keys (in this situation URIs) are changed by version, clients can easily cache resources. When a new version of the REST API is released, it is perceived as a new entry in the cache.

Pros: Clients can cache resources easily Cons: This solution has a pretty big footprint in the code base as introducing breaking changes implies branching the entire API

Ref: https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/#:~:text=Clients%20may%20not%20want%20to,API%20when%20they%20are%20ready.