How to approach REST API path parameter versioning?

Question

Question

I'm trying to figure out what would be the best approach on path parameter versioning, but haven't been able to find a good/trustful source.

Say you have two entities category and product and the following REST endpoint to obtain the products within a given category reference.

GET /categories/{categoryReference}/products

You entity has a legacy categoryReference which needs to be supported as well, what would be the best approach. I've got two approaches on my mind. What would be the best way of doing it and why? (if there's other way, please feel free to add it).

Option 1: New Endpoint

Given that you have a "new" parameter the endpoint should be new:

GET /categories/oldCatRef/{oldCategoryReference}/products

Option 2: A query param

Given that you are modifying the query by filtering with a different param:

GET /categories/{oldCategoryReference}/products?usingOldCatRef=true

Answer 1

It is very simple, all you have to do is to use the a single endpoint as follows

GET /categoryProducts

And then, in the body, you accept both values in a JSON, taking into account which of thosr have prelation (my advice is to use the new one). If you receive one or the other you will have the business logic in the controller:

{
  "categoryRef" : "new",
  "oldCategoryRef" : "old"
}

No need to use path parameters or query params in this query.