Merge pull request goadesign#319 from goadesign/versioning_mux

Add DSL for defining param, header and querystring based versioning

Author: Raphaël Simon

design/api.go

@@ -82,6 +82,15 @@ type (
 		Types map[string]*UserTypeDefinition
 		// MediaTypes indexes the API media types by canonical identifier.
 		MediaTypes map[string]*MediaTypeDefinition
+		// VersionParams list the names of the path parameter wildcards that may contain
+		// the name of the targeted API version.
+		VersionParams []string
+		// VersionHeaders list the names of the HTTP request headers that may contain the
+		// name of the targeted API version.
+		VersionHeaders []string
+		// VersionQueries list the names of the HTTP request querystrings that may contain
+		// the name of the targeted API version.
+		VersionQueries []string
 		// rand is the random generator used to generate examples.
 		rand *RandomGenerator
 	}

design/apidsl/api.go

@@ -16,6 +16,9 @@ import (
 //	API("API name", func() {
 //		Title("title")				// API title used in documentation
 //		Description("description")		// API description used in documentation
+//		VersionParam("version")			// Path param that captures targeted version, can appear 0 or more times
+//		VersionHeader("X-Api-Version") 		// Request header that captures targeted version, can appear 0 or more times
+//		VersionQuery("version")			// Querystring value that captures targeted version, can appear 0 or more times
 //		TermsOfService("terms")
 //		Contact(func() {			// API Contact information
 //			Name("contact name")
@@ -32,7 +35,7 @@ import (
 //		})
 //		Host("goa.design")			// API hostname
 //		Scheme("http")
-//		BasePath("/base/:param")		// Common base path to all API actions
+//		BasePath("/base/:version/:param")	// Common base path to all API actions
 //		BaseParams(func() {			// Common parameters to all API actions
 //			Param("param")
 //		})
@@ -78,7 +81,22 @@ func API(name string, dsl func()) *design.APIDefinition {
 
 // Version is the top level design language function which defines the API global property values
 // for a given version. The DSL used to define the property values is identical to the one used by
-// the API function.
+// the API function. Here is an example that shows a *subset* of the Version
+// DSL (see the API function for all the other possible functions).
+//
+//	Version("2.0", func() {
+//		Title("API v2")		       // API version 2.0 title used in documentation
+//		Description("This is v2")      // API version description used in documentation
+//	 	Docs(func() {
+//			Description("v2 docs")
+//			URL("v2 doc URL")
+//		})
+//		BasePath("/v2")		       // Common base path to all actions exposed by this API version
+//		VersionHeader("X-Api-Version") // Usually only useful if BasePath is same as API
+//		VersionQuery("version")        // Generated code considers header first if specified then querystring
+//		VersionQuery("v")	       // Multiple version headers or querystrings may be specified
+//              VersionQuery("version", "v")   // Equivalent to the two lines above
+//	})
 func Version(ver string, dsl func()) *design.APIVersionDefinition {
 	verdef := &design.APIVersionDefinition{Version: ver, DSLFunc: dsl}
 	if _, ok := design.Design.APIVersions[ver]; ok {
@@ -95,6 +113,66 @@ func Version(ver string, dsl func()) *design.APIVersionDefinition {
 	return verdef
 }
 
+// VersionParam defines the name of the request path parameter that contains the targeted API version.
+// Multiple names may be specified in which case the value of the first to correspond to the name
+// of a param is used.
+func VersionParam(names ...string) {
+	if api, ok := apiDefinition(true); ok {
+		for _, n := range names {
+			found := false
+			for _, n2 := range api.VersionParams {
+				if n == n2 {
+					found = true
+					break
+				}
+			}
+			if !found {
+				api.VersionParams = append(api.VersionParams, n)
+			}
+		}
+	}
+}
+
+// VersionHeader defines the name of the HTTP request header that contains the targeted API version.
+// Multiple names may be specified in which case the value of the first to correspond to the name
+// of a header is used.
+func VersionHeader(names ...string) {
+	if api, ok := apiDefinition(true); ok {
+		for _, n := range names {
+			found := false
+			for _, n2 := range api.VersionHeaders {
+				if n == n2 {
+					found = true
+					break
+				}
+			}
+			if !found {
+				api.VersionHeaders = append(api.VersionHeaders, n)
+			}
+		}
+	}
+}
+
+// VersionQuery defines the name of the querystring that contains the targeted API version.
+// Multiple names may be specified in which case the value of the first to correspond to the name
+// of a querystring is used.
+func VersionQuery(names ...string) {
+	if api, ok := apiDefinition(true); ok {
+		for _, n := range names {
+			found := false
+			for _, n2 := range api.VersionQueries {
+				if n == n2 {
+					found = true
+					break
+				}
+			}
+			if !found {
+				api.VersionQueries = append(api.VersionQueries, n)
+			}
+		}
+	}
+}
+
 // Description sets the definition description.
 // Description can be called inside API, Resource, Action or MediaType.
 func Description(d string) {

design/apidsl/api_test.go

@@ -315,4 +315,110 @@ var _ = Describe("API", func() {
 			})
 		})
 	})
+
+	Context("using VersionParam", func() {
+		const vparam = "version"
+		BeforeEach(func() {
+			name = "v1"
+			dsl = func() {
+				BasePath("/api/:" + vparam)
+				VersionParam(vparam)
+			}
+		})
+
+		It("stores the version header name", func() {
+			Ω(Design.Validate()).ShouldNot(HaveOccurred())
+			Ω(Design.VersionParams).Should(Equal([]string{vparam}))
+		})
+	})
+
+	Context("using VersionHeader", func() {
+		const vheader = "X-Api-Version"
+		BeforeEach(func() {
+			name = "v1"
+			dsl = func() {
+				VersionHeader(vheader)
+			}
+		})
+
+		It("stores the version header name", func() {
+			Ω(Design.Validate()).ShouldNot(HaveOccurred())
+			Ω(Design.VersionHeaders).Should(Equal([]string{vheader}))
+		})
+	})
+
+	Context("using VersionQuery", func() {
+		const vquery = "version"
+		BeforeEach(func() {
+			name = "v1"
+			dsl = func() {
+				VersionQuery(vquery)
+			}
+		})
+
+		It("stores the version query name", func() {
+			Ω(Design.Validate()).ShouldNot(HaveOccurred())
+			Ω(Design.VersionQueries).Should(Equal([]string{vquery}))
+		})
+	})
+
+	Context("using VersionHeader to specify duplicates", func() {
+		const vheader = "X-Api-Version"
+		BeforeEach(func() {
+			name = "v1"
+			dsl = func() {
+				VersionHeader(vheader)
+				VersionHeader(vheader)
+			}
+		})
+
+		It("stores the version header name only once", func() {
+			Ω(Design.Validate()).ShouldNot(HaveOccurred())
+			Ω(Design.VersionHeaders).Should(Equal([]string{vheader}))
+		})
+	})
+
+	Context("using VersionQuery to specify duplicates", func() {
+		const vquery = "version"
+		BeforeEach(func() {
+			name = "v1"
+			dsl = func() {
+				VersionQuery(vquery, vquery)
+			}
+		})
+
+		It("stores the version query name only once", func() {
+			Ω(Design.Validate()).ShouldNot(HaveOccurred())
+			Ω(Design.VersionQueries).Should(Equal([]string{vquery}))
+		})
+	})
+})
+
+var _ = Describe("Version", func() {
+	var name string
+	var dsl func()
+
+	BeforeEach(func() {
+		InitDesign()
+		dslengine.Errors = nil
+		name = ""
+		dsl = nil
+	})
+
+	JustBeforeEach(func() {
+		Version(name, dsl)
+		dslengine.Run()
+	})
+
+	Context("with no DSL", func() {
+		BeforeEach(func() {
+			name = "v1"
+		})
+
+		It("produces a valid version definition", func() {
+			Ω(Design.Validate()).ShouldNot(HaveOccurred())
+			Ω(Design.Versions()).Should(HaveLen(1))
+			Ω(Design.Versions()[0]).Should(Equal(name))
+		})
+	})
 })

design/validation.go

@@ -71,6 +71,7 @@ func (a *APIDefinition) Validate() error {
 	a.validateContact(verr)
 	a.validateLicense(verr)
 	a.validateDocs(verr)
+	a.validateVersionParams(verr)
 
 	a.IterateVersions(func(ver *APIVersionDefinition) error {
 		var allRoutes []*routeInfo
@@ -179,6 +180,23 @@ func (a *APIDefinition) validateDocs(verr *dslengine.ValidationErrors) {
 	}
 }
 
+func (a *APIDefinition) validateVersionParams(verr *dslengine.ValidationErrors) {
+	bwcs := ExtractWildcards(a.BasePath)
+	for _, param := range a.VersionParams {
+		found := false
+		for _, wc := range bwcs {
+			if wc == param {
+				found = true
+				break
+			}
+		}
+		if !found {
+			verr.Add(a, "invalid version param, %s is not an API base path param (base path is %#v)",
+				param, a.BasePath)
+		}
+	}
+}
+
 // Validate tests whether the resource definition is consistent: action names are valid and each action is
 // valid.
 func (r *ResourceDefinition) Validate(version *APIVersionDefinition) *dslengine.ValidationErrors {

doc.go

@@ -69,8 +69,7 @@ The definitions of the Bottle and UpdateBottlePayload data structures are ommitt
 Controllers
 
 There is one controller interface generated per resource defined via the design language. The
-interface exposes the controller actions as well as methods to set controller specific middleware
-and error handlers (see below). User code must provide data structures that implement these
+interface exposes the controller actions. User code must provide data structures that implement these
 interfaces when mounting a controller onto a service. The controller data structure should include
 an anonymous field of type *goa.Controller which takes care of implementing the middleware and
 error handler handling.
@@ -113,5 +112,12 @@ input (Consumes) and output (Produces). goagen uses that information to registed
 packages with the service encoders and decoders via the SetEncoder and SetDecoder methods. The
 service exposes the Decode, DecodeRequest, Encode and EncodeResponse that implement a simple content
 type negotiation algorithm for picking the right encoder for the "Accept" request header.
+
+Versioning
+
+The VersionMux interface implemented by the RootMux struct exposes methods used by the generated
+code to setup the routing to versioned endpoints. The DSL defines how the API handles versioning:
+via request path, header, querystring or a combination. The generated code uses the VersionMux
+interface to setup the root mux accordingly.
 */
 package goa

goagen/gen_app/generator.go

@@ -328,7 +328,7 @@ func (g *Generator) generateControllers(verdir string, version *design.APIVersio
 		if !r.SupportsVersion(version.Version) {
 			return nil
 		}
-		data := &ControllerTemplateData{Resource: codegen.Goify(r.Name, true)}
+		data := &ControllerTemplateData{API: design.Design, Resource: codegen.Goify(r.Name, true)}
 		err := r.IterateActions(func(a *design.ActionDefinition) error {
 			context := fmt.Sprintf("%s%sContext", codegen.Goify(a.Name, true), codegen.Goify(r.Name, true))
 			unmarshal := fmt.Sprintf("unmarshal%s%sPayload", codegen.Goify(a.Name, true), codegen.Goify(r.Name, true))

goagen/gen_app/generator_test.go

@@ -430,6 +430,19 @@ import (
 	"net/http"
 )
 
+// inited is true if initService has been called
+var inited = false
+
+// initService sets up the service encoders, decoders and mux.
+func initService(service *goa.Service) {
+	if inited {
+		return
+	}
+	inited = true
+	// Setup encoders and decoders
+
+}
+
 // WidgetController is the controller interface for the Widget actions.
 type WidgetController interface {
 	goa.Muxer
@@ -438,17 +451,15 @@ type WidgetController interface {
 
 // MountWidgetController "mounts" a Widget resource controller on the given service.
 func MountWidgetController(service *goa.Service, ctrl WidgetController) {
-	// Setup encoders and decoders. This is idempotent and is done by each MountXXX function.
-
-	// Setup endpoint handler
+	initService(service)
 	var h goa.Handler
 	mux := service.{{if .version}}Version("{{.version}}").Mux{{else}}Mux{{end}}
 	h = func(ctx context.Context, rw http.ResponseWriter, req *http.Request) error {
 		rctx, err := NewGetWidgetContext(ctx)
 		if err != nil {
 			return goa.NewBadRequestError(err)
 		}{{if .version}}
-		rctx.APIVersion = service.Version("{{.version}}").VersionName{{end}}
+		rctx.APIVersion = "{{.version}}"{{end}}
 		return ctrl.Get(rctx)
 	}
 	mux.Handle("GET", "/:id", ctrl.MuxHandler("Get", h, nil))
@@ -494,9 +505,7 @@ package app
 const controllersSlicePayloadCode = `
 // MountWidgetController "mounts" a Widget resource controller on the given service.
 func MountWidgetController(service *goa.Service, ctrl WidgetController) {
-	// Setup encoders and decoders. This is idempotent and is done by each MountXXX function.
-
-	// Setup endpoint handler
+	initService(service)
 	var h goa.Handler
 	mux := service.Mux
 	h = func(ctx context.Context, rw http.ResponseWriter, req *http.Request) error {