Alluded to earlier, there exists a grouping capability for defined routes within the Echo framework. Grouping of routes allows for simple logical groupings of sets of resources with a base prefix. A great example that works well with grouped routes is when you wish to have a target resource path versioned API, such as providing /v1/login and /v1/logout, as well as /v2/login and /v2/logout. This happens to be a very common way in which developers can prevent breakage of their API from major changes to the API. Typically, if the schema of the request or response changes, it is a best practice to create a new version of those resource targets. This helps identify to developers integrating with your API that there is a breaking change between the two APIs.
In this example, we would create a /v1/ and a /v2 group with the Group method, which is declared in the following code within Echo:
func (e *Echo) Group(prefix string, m ...MiddlewareFunc) (g *Group) {
Within this Group method call, we must provide a prefix string as well as an optional middleware chain that is applicable to this group of resources. The Group return value contains a number of methods; most importantly are exactly the same route mapping functions that we are given with Echo: Add, Any, GET, POST, PUT, and so on. The following is a more fleshed out example based on our example project, which can be seen in the $GOPATH/src/github.com/PacktPublishing/Echo-Essentials/chapter3/cmd/service/main.go file:
// V1 Routes
v1 := e.Group("/v1")
// V1 Authentication routes
v1.POST("/login", handlers.Login)
v1.POST("/logout", handlers.Logout)
// V1 Reminder Routes
v1Reminders := v1.Group("/reminder", middleware.JWT(signingKey))
v1Reminders.POST("", handlers.CreateReminder)
As you can see, grouping allows flexibility in defining responsible API resource target paths. First off, we create our main Echo instance group with the prefix of /v1, upon which we are adding /login and /logout. A very handy feature within the framework is the ability to create groups within groups. You can see that our /reminder is created off of our /v1 group.
Under the covers, the grouping mechanism merely wraps the Echo instance's Add function. This means that all group routes are applied to the Echo router's tree data structure by first applying the prefix of the group onto the path, and then inserting the routes into the Echo instance's router.
Regardless of whether you choose grouped routes or enumerating each route in full, understand that your routes will be matched identically. It is fairly common for API endpoints to allow either a trailing slash, or to not depend on the caller's personal preference. Based on our discussion so far, it is easy to see how this could cause problems, as our router will perform exact string matching based on the provided path. If, for example, we have a route set up, shown as follows, and we perform an HTTP call with a trailing slash, we will run into a Not Found situation:
e.POST(“/login”, handlers.Login)
If we perform a call to this service, as shown in the following code, you will get a Not Found HTTP response code in the response. This is due to the fact that we do not have an exact match to /login in our request target path:
curl -XPOST http://localhost:8080/login/ -D - HTTP/1.1 404 Not Found Content-Type: application/json; charset=UTF-8 Date: Sun, 06 May 2018 16:22:09 GMT Content-Length: 23 {"message":"Not Found"}
It is fairly typical for APIs to accept both versions, a trailing slash as well as a no trailing slash, and route them to the same handler. This, however, would become cumbersome if we created two routes for every single endpoint we wished to serve from the service. A good solution for this is to use the TrailingSlash middleware that comes bundled with Echo. We will explain how to use this middleware in depth within Chapter 4, Implementing Middleware, but using a middleware solution like TrailingSlash will allow you to outline your routes either with a trailing slash, or not, and the middleware will take care of the trailing slash for you prior to routing.
Considerations such as these must be in your mind when creating new APIs for consumption. To that end, the next section of this chapter will outline in detail particular implementation considerations for target path routers and attempt to shed some light on the positives and negatives related to different implementations.