README auto-gen (add the API-Versioning example)

Author: ant0ine

README.md

@@ -46,6 +46,7 @@ In fact the internal code of **go-json-rest** is itself implemented with Middlew
   - [Advanced](#advanced)
 	  - [Streaming](#streaming)
 	  - [Non JSON payload](#non-json-payload)
+	  - [API Versioning](#api-versioning)
 	  - [SPDY](#spdy)
 	  - [Google App Engine](#gae)
 	  - [Basic Auth Custom](#basic-auth-custom)
@@ -1020,6 +1021,110 @@ func main() {
 
 ```
 
+#### API Versioning
+
+First, API versioning is not easy and you may want to favor a mechanism that uses only backward compatible changes and deprecation cycles.
+
+That been said, here is an example of API versioning using [Semver](http://semver.org/)
+
+It defines a middleware that parses the version, checks a min and a max, and makes it available in the `request.Env`.
+
+(TODO, there is an obvious need for PostRoutingMiddlewares here.)
+
+The curl demo:
+``` sh
+curl -i http://127.0.0.1:8080/api/1.0.0/message
+curl -i http://127.0.0.1:8080/api/2.0.0/message
+curl -i http://127.0.0.1:8080/api/2.0.1/message
+curl -i http://127.0.0.1:8080/api/0.0.1/message
+curl -i http://127.0.0.1:8080/api/4.0.1/message
+
+```
+
+
+Go code:
+``` go
+package main
+
+import (
+	"github.com/ant0ine/go-json-rest/rest"
+	"github.com/coreos/go-semver/semver"
+	"log"
+	"net/http"
+)
+
+type SemVerMiddleware struct {
+	MinVersion string
+	MaxVersion string
+}
+
+func (mw *SemVerMiddleware) MiddlewareFunc(handler rest.HandlerFunc) rest.HandlerFunc {
+
+	minVersion, err := semver.NewVersion(mw.MinVersion)
+	if err != nil {
+		panic(err)
+	}
+
+	maxVersion, err := semver.NewVersion(mw.MaxVersion)
+	if err != nil {
+		panic(err)
+	}
+
+	return func(writer rest.ResponseWriter, request *rest.Request) {
+
+		version, err := semver.NewVersion(request.PathParam("version"))
+		if err != nil {
+			rest.Error(writer, "Invalid version: "+err.Error(), http.StatusBadRequest)
+			return
+		}
+
+		if version.LessThan(*minVersion) {
+			rest.Error(writer, "Min supported version is "+minVersion.String(), http.StatusBadRequest)
+			return
+		}
+
+		if maxVersion.LessThan(*version) {
+			rest.Error(writer, "Max supported version is "+maxVersion.String(), http.StatusBadRequest)
+			return
+		}
+
+		request.Env["VERSION"] = version
+		handler(writer, request)
+	}
+}
+
+type Message struct {
+	Body string
+}
+
+func main() {
+	handler := rest.ResourceHandler{}
+	svmw := SemVerMiddleware{
+		MinVersion: "1.0.0",
+		MaxVersion: "3.0.0",
+	}
+	err := handler.SetRoutes(
+		&rest.Route{"GET", "/#version/message", svmw.MiddlewareFunc(
+			func(w rest.ResponseWriter, req *rest.Request) {
+				version := req.Env["VERSION"].(*semver.Version)
+				if version.Major == 2 {
+                                        // http://en.wikipedia.org/wiki/Second-system_effect
+					w.WriteJson(&Message{"Hello broken World!"})
+				} else {
+					w.WriteJson(&Message{"Hello World!"})
+				}
+			},
+		)},
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+	http.Handle("/api/", http.StripPrefix("/api", &handler))
+	log.Fatal(http.ListenAndServe(":8080", nil))
+}
+
+```
+
 #### SPDY
 
 Demonstrate how to use SPDY with https://github.com/shykes/spdy-go