echo/website/docs/guide.md

Guide

---

Installation

Echo has been developed and tested using Go 1.4.x

Install the latest version of Echo via go get

$ go get github.com/labstack/echo

To upgrade

$ go get -u github.com/labstack/echo

Echo follows semantic versioning managed through GitHub releases. Specific version of Echo can be installed using any package manager.

Customization

Max path parameters

echo.MaxParam(n uint8)

Sets the maximum number of path parameters allowed for the application. Default value is 5, good enough for many use cases. Restricting path parameters allows us to use memory efficiently.

HTTP error handler

echo.HTTPErrorHandler(h HTTPErrorHandler)

Registers a custom centralized HTTP error handler func(*HTTPError, *Context).

Default handler sends HTTPError.Message HTTP response with HTTPError.Code status code.

• If HTTPError.Code is not specified it uses "500 - Internal Server Error".
• If HTTPError.Message is not specified it uses HTTPError.Error.Error() or the status code text.

Routing

Echo's router is fast, optimized and flexible. It's based on redix tree data structure which makes routing lookup really fast. It leverages sync pool to reuse memory and achieve zero dynamic memory allocation with no GC overhead.

Routes can be registered by specifying HTTP method, path and a handler. For example, code below registers a route for method GET, path /hello and a handler which sends Hello! HTTP response.

echo.Get("/hello", func(*echo.Context) *HTTPError {
	return c.String(http.StatusOK, "Hello!")
})

Echo's default handler is func(*echo.Context) *echo.HTTPError where echo.Context primarily holds HTTP request and response objects. Echo also has a support for other types of handlers.

Group

WIP

Path parameter

Request path parameters can be extracted either by name echo.Context.Param(name string) string or by index echo.Context.P(i uint8) string. Getting parameter by index gives a slightly better performance.

echo.Get("/users/:id", func(c *echo.Context) *HTTPError {
	// By name
	id := c.Param("id")

	// By index
	id := c.P(0)

	return c.String(http.StatusOK, id)
})

Match-any

Matches zero or more characters in the path. For example, pattern /users/* will match

• /users/
• /users/1
• /users/1/files/1
• /users/anything...

Path matching order

• Static
• Param
• Match any

Example

e.Get("/users/:id", func(c *echo.Context) *HTTPError {
	return c.String(http.StatusOK, "/users/:id")
})

e.Get("/users/new", func(c *echo.Context) *HTTPError {
	return c.String(http.StatusOK, "/users/new")
})

e.Get("/users/1/files/*", func(c *echo.Context) *HTTPError {
	return c.String(http.StatusOK, "/users/1/files/*")
})

Above routes would resolve in order

• /users/new
• /users/:id
• /users/1/files/*

Routes can be written in any order.

URI building

echo.URI can be used generate URI for any handler with specified path parameters. It's helpful to centralize all your URI patterns which ease in refactoring your application.

echo.URI(h, 1) will generate /users/1 for the route registered below

// Handler
h := func(*echo.Context) *HTTPError {
	return c.String(http.StatusOK, "OK")
}

// Route
e.Get("/users/:id", h)

Middleware

WIP

Response

JSON

context.JSON(code int, v interface{}) *HTTPError

Sends a JSON HTTP response with status code.

String

context.String(code int, s string) *HTTPError

Sends a text/plain HTTP response with status code.

HTML

func (c *Context) HTML(code int, html string) *HTTPError

Sends an HTML HTTP response with status code.

Static files

echo.Static(path, root string) serves static files. For example, code below serves files from directory public/scripts for any request path starting with /scripts/.

e.Static("/scripts/", "public/scripts")

Serving a file

echo.ServeFile(path, file string) serves a file. For example, code below serves file welcome.html for request path /welcome.

e.ServeFile("/welcome", "welcome.html")

Serving an index file

echo.Index(file string) serves root index page - GET /. For example, code below serves root index page from file public/index.html.

e.Index("public/index.html")

Serving favicon

echo.Favicon(file string) serves default favicon - GET /favicon.ico. For example, code below serves favicon from file public/favicon.ico.

e.Index("public/favicon.ico")

Error Handling

Echo advocates centralized HTTP error handling by returning *echo.HTTPError from middleware and handlers.

It allows you to

• Debug by writing stack trace to the HTTP response.
• Customize HTTP responses.
• Recover from panics inside middleware or handlers.

For example, when a basic auth middleware finds invalid credentials it returns 401 "Unauthorized" error, aborting the current HTTP request.

package main

import (
	"net/http"

	"github.com/labstack/echo"
)

func main() {
	e := echo.New()
	e.Use(func(c *echo.Context) *echo.HTTPError {
		// Extract the credentials from HTTP request header and perform a security
		// check

		// For invalid credentials
		return &echo.HTTPError{Code: http.StatusUnauthorized}
	})
	e.Get("/welcome", welcome)
	e.Run(":1323")
}

func welcome(c *echo.Context) *echo.HTTPError {
	return c.String(http.StatusOK, "Welcome!")
}

See how HTTPErrorHandler handles it.

Deployment

WIP