RESTful API Versioning

This document provides an insights into REST API versioning strategies supported by aah. API versioning allows you to alter behavior or application logic flow between different clients.

There are a number of valid strategies to approach API versioning. Typically API versioning is determined by the incoming client request, and may either be based on the request URL, request URL query parameter, request HTTP headers or HostName.

• Strategy: URL Path
• Strategy: Accept Header Versioning
• Strategy: Accept Header with Vendor Media Type
• Strategy: URL Query Parameter
• Strategy: HostName

Wondering: As of now, aah user have to fetch version info according to versioning strategy they choose. Not sure, is it worth have one Method returns the version number based on chosen strategy. Let me know your thoughts.

Strategy: URL Path

This strategy requires the client to specify the version as part of the URL path.

For example:

GET /v1/users

Your routes.conf include Named parameter with key as a version. So that version info available to you in the controller via ctx.Req.PathValue("version").

routes {
  path = "/:version"

  routes {
    path = "/users"

    # ...
  }
}

Strategy: Accept Header Versioning

This strategy requires the client to specify the version as part of the media type in the HTTP Accept header. The version is included as a media type parameter, that supplements the main media type.

For example: HTTP request using the accept header versioning strategy.

GET /v1/users
Accept: application/json; version=2.0

You can access version info via ctx.Req.AcceptContentType.Version().

Strategy: Accept Header with Vendor Media Type

This strategy requires the client to specify the version as part of the vendor media type in the HTTP Accept header.

For example: HTTP request using the accept header with vendor media type strategy.

GET /v1/users
Accept: application/vnd.mycompany.myapp.customer-v2.2+json

You can access:

• version info using ctx.Req.AcceptContentType.Version()
• vendor info using ctx.Req.AcceptContentType.Vendor()

Strategy: URL Query Parameter

This strategy is a simple style that includes the version as a URL query parameter.

For example:

GET /users?version=1.1

You can access version info via ctx.Req.QueryValue("version").

Strategy: HostName

This strategy requires the client to specify the requested version as part of the hostname in the URL.

For example:

# The following is an HTTP request to the URL: http://v1.sample.com/users/

GET /users
Host: v1.sample.com

You can access version info via ctx.Subdomain().

For example:

127.0.0.1 sample.com v1.sample.com