0

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){
       // ...
    }
}
5

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.

  • I recall reading some Restafarian rail on about how versioning should be handled with MIME types but I've never seen that as practical. The problem with all these "is this the right way to do REST" is that it's not clear whether we are talking about REST as defined by Fielding or REST as defined by e.g. swagger. – JimmyJames May 24 at 13:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.