Versioning using the URI

A common approach is to use the URI to version APIs (although this approach is discouraged in favour of Hypermedia). For example, you can define the following URL mappings:

That will match the following controllers:

class BookController {
    static namespace = 'v1'
package myapp.v2
    static namespace = 'v2'
}

Versioning with the Accept-Version header

As an alternative Grails supports the passing of an Accept-Version header from clients. For example you can define the following URL mappings:

Then in the client simply pass which version you need using the Accept-Version header:

$ curl -i -H "Accept-Version: 1.0" -X GET http://localhost:8080/books

Versioning using Hypermedia / Mime Types

Then override the renderer (see the section on "Customizing Response Rendering" for more information on custom renderers) to send back the custom Mime Type in grails-app/conf/spring/resourses.groovy:

import grails.web.mime.*
beans = {
    bookRendererV1(JsonRenderer, myapp.v1.Book, new MimeType("application/vnd.books.org.book+json", [v:"1.0"]))
    bookRendererV2(JsonRenderer, myapp.v2.Book, new MimeType("application/vnd.books.org.book+json", [v:"2.0"]))
}

Then update the list of acceptable response formats in your controller: