RESTful API Endpoints - Concrete vs OO versioning

Question

I am looking at Versioning Micro Services solutions and got a little carried away with OO design. Using WebAPI, I got to the point where I can use OO design to choose the correct version to run with only a single endpoint. But is it good practice to reduce the endpoints like this?

I admire the SOLID-ness/OO-ness of having a single Endpoint, however I think it may go against RESTful WebAPI practices. I'm also not sure how nicely it will play with tools such as Swagger (probably wont play nice).

What is the general preference between:

A) An API with a single Endpoint to for each Action. Version passed to it as part of the request, and the OO design then determines what inner logic to run.

DoStuffRestfulAPI{

    GetStuff(version){
       // use OO to execute correct version of GetStuff.
       // I'm using a Command pattern to contain logic.
    }

    GetSingleStuff(version, stuffId){
       // ...
    }
}

OR

b) An API with multiple Endpoints to expose every Version of each Action.

DoStuffRestfulAPI{

    GetStuffV1(){
       // we know which version to run, so just run it as a concrete call
    }

    GetStuffV2(){
       // ...
    }

    GetStuffV3(){
       // ...
    }

    GetSingleStuffV1(stuffId){
       // ...
    }

    GetSingleStuffV2(stuffId){
       // ...
    }
}

Answer 1

Dynamically selecting the correct API implementation sounds cool, but is actually a nightmare.

• a REST API exposes a bunch of URIs that identify resources
• cool URIs don't change
• here, the interpretation of the URI depends on the implicit version
• so your URIs do not identify resources by themselves
• this breaks REST, to some degree

Your implicit version scheme seems to work because all of your API versions are quite similar. But once they evolve into different shapes, you will find it very difficult to create a common interface to manage the dispatch to the correct version.

The better approach would be to treat your versions as entirely separate APIs that are deployed side by side. Under the hood the API might be served by a common process, and the API implementations might share common code. But that is an implementation detail that should not be visible from the outside.