Gracefully way to handle REST Service versioning with vert.x?

[Hải Đăng Nguyễn]

Our microservices was written like this:

router.get("/v1/hello").handler(...)
router.get("/v1/resource/...").handler(...)

However, when the service needs versioning, handle it the regular way seem to be very verbose:

router.get("/v1/hello").handler(...)
router.get("/v1/resource/...").handler(...)
router.get("/v2/hello").handler(...)
router.get("/v2/resource/...").handler(...)

Do you have any idea to handle this? Thank you :)

[llfbandit]

Hi,

since you have two API, you'll have also two paths or code branches.
I would suggest to not prefix with the version but handling it as query parameter.
Let's say:

router.get("/v1/hello").handler(...) // for your V1, I guess you can't do anything

router.get("/hello").handler(...) // always for the latest API version to let your clients upgrade seamlessly if possible.

router.get("/hello").handler(rc -> {
   String version = rc.request().getParam("api_version") // re-route or call the dedicated consumer behind
   if (version != null && version.equals("1.152") {
     // client call explicitly V1.152 service
   }
)


Hope this helps !

[Clement Escoffier]

Hi,

There are different ways more or less restful (but that’s more a question of taste):

1. in the path as you proposed initially

2. as a query parameter 

3. in a HTTP header (X-Version, or better X-Accept-Version, with a response containing X-Version and Vary)

1 is probably the most used because it’s easy, but as suggested, I would prefer 2 (but again it’s a matter of taste).

3 is the most powerful because you can select the version on the server side and write the VARY header to explain on which criteria you did. However, it’s harder to test in a browser as you need a REST client to pass the header.

Clement

--
You received this message because you are subscribed to the Google Groups "vert.x" group.
To unsubscribe from this group and stop receiving emails from it, send an email to vertx+un...@googlegroups.com.
Visit this group at https://groups.google.com/group/vertx.
To view this discussion on the web, visit https://groups.google.com/d/msgid/vertx/5b0c5eb8-f865-4f85-be91-bca2385c8e89%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.