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.

Not found handler

echo.NotFoundHandler(h Handler)

Registers a custom NotFound handler. This handler is called in case router doesn't find matching route for the request.

Default handler sends 404 "Not Found" response.

HTTP error handler

echo.HTTPErrorHandler(h HTTPErrorHandler)

Registers a custom centralized HTTP error handler.

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 for any HTTP method, path and handler. For example, code below registers a route for method GET, path /hello and a handler which sends Hello! 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 request and response objects. Echo also has a support for other types of handlers.

Path parameters

URL 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)

Response

JSON

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

Sends a JSON response with status code.

String

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

Sends a text/plain response with status code.

HTML

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

Sends an HTML response with status code.

Static files

echo.Static(path, root string) serves static files. For example, code below serves all files from public/scripts directory for any 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 welcome.html for path /welcome

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

Serving an index file

echo.Index(file string) serves an index file. For example, code below serves index.html for path /

e.Index("index.html")