echo/README.md

NOTICE

• Master branch, website and godoc now points to Echo v2.
• Echo v2 is in beta but if you want to try it out here is the migrating [guide] (https://labstack.com/echo/guide/migrating)
• Looking for v1?
  • Installation: Use a package manager (https://github.com/Masterminds/glide, it's nice!) to get stable v1 release/commit or use go get gopkg.in/labstack/echo.v1.
  • Godoc: https://godoc.org/gopkg.in/labstack/echo.v1
  • Docs: https://github.com/labstack/echo/tree/v1.4/website/content

Echo

Echo is a fast and unfancy HTTP server framework for Go (Golang). Up to 10x faster than the rest.

Features

• Optimized HTTP router which smartly prioritize routes.
• Build robust and scalable RESTful APIs.
• Run with standard HTTP server or FastHTTP server.
• Group APIs.
• Extensible middleware framework.
• Define middleware at root, group or route level.
• Data binding for JSON, XML and form payload.
• Handy functions to send variety of HTTP responses.
• Centralized HTTP error handling.
• Template rendering with any template engine.
• Define your format for the logger.
• Highly customizable.

Performance

• Environment:
  • Go 1.6
  • wrk 4.0.0
  • 2 GB, 2 Core (DigitalOcean)
• Test Suite: https://github.com/vishr/web-framework-benchmark
• Date: 4/4/2016

Quick Start

Installation

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

Hello, World!

Create server.go

package main

import (
	"net/http"
	"github.com/labstack/echo"
	"github.com/labstack/echo/engine/standard"
)

func main() {
	e := echo.New()
	e.GET("/", func(c echo.Context) error {
		return c.String(http.StatusOK, "Hello, World!")
	})
	e.Run(standard.New(":1323"))
}

Start server

$ go run server.go

Browse to http://localhost:1323 and you should see Hello, World! on the page.

Routing

e.POST("/users", saveUser)
e.GET("/users/:id", getUser)
e.PUT("/users/:id", updateUser)
e.DELETE("/users/:id", deleteUser)

Path Parameters

func getUser(c echo.Context) error {
	// User ID from path `users/:id`
	id := c.Param("id")
}

Query Parameters

/show?team=x-men&member=wolverine

func show(c echo.Context) error {
	// Get team and member from the query string
	team := c.QueryParam("team")
	member := c.QueryParam("member")
}

Form application/x-www-form-urlencoded

POST /save

name	value
name	Joe Smith
email	joe@labstack.com

func save(c echo.Context) error {
	// Get name and email
	name := c.FormValue("name")
	email := c.FormValue("email")
}

Form multipart/form-data

POST /save

name	value
name	Joe Smith
email	joe@labstack.com
avatar	avatar

func save(c echo.Context) error {
	// Get name and email
	name := c.FormValue("name")
	email := c.FormValue("email")
	// Get avatar
	avatar, err := c.FormFile("avatar")
	if err != nil {
		return err
	}

	// Source
	src, err := avatar.Open()
	if err != nil {
		return err
	}
	defer src.Close()

	// Destination
	dst, err := os.Create(avatar.Filename)
	if err != nil {
		return err
	}
	defer dst.Close()

	// Copy
	if _, err = io.Copy(dst, src); err != nil {
		return err
	}

	return c.HTML(http.StatusOK, "<b>Thank you!</b>")
}

Handling Request

• Bind JSON or XML or form payload into Go struct based on Content-Type request header.
• Render response as JSON or XML with status code.

type User struct {
	Name  string `json:"name" xml:"name" form:"name"`
	Email string `json:"email" xml:"email" form:"email"`
}

e.POST("/users", func(c echo.Context) error {
	u := new(User)
	if err := c.Bind(u); err != nil {
		return err
	}
	return c.JSON(http.StatusCreated, u)
	// or
	// return c.XML(http.StatusCreated, u)
})

Static Content

Server any file from static directory for path /static/*.

e.Static("/static", "static")

More...

Template Rendering

Middleware

// Root level middleware
e.Use(middleware.Logger())
e.Use(middleware.Recover())

// Group level middleware
g := e.Group("/admin")
g.Use(middleware.BasicAuth(func(username, password string) bool {
	if username == "joe" && password == "secret" {
		return true
	}
	return false
}))

// Route level middleware
track := func(next echo.HandlerFunc) echo.HandlerFunc {
	return func(c echo.Context) error {
		println("request to /users")
		return next(c)
	}
}
e.GET("/users", func(c echo.Context) error {
	return c.String(http.StatusOK, "/users")
}, track)

Built-in Middleware

Middleware	Description
BodyLimit	Limit request body
Logger	Log HTTP requests
Recover	Recover from panics
Gzip	Send gzip HTTP response
BasicAuth	HTTP basic authentication
JWTAuth	JWT authentication
Secure	Protection against attacks
CORS	Cross-Origin Resource Sharing
Static	Serve static files
AddTrailingSlash	Add trailing slash to the request URI
RemoveTrailingSlash	Remove trailing slash from the request URI
MethodOverride	Override request method

More...

Third-party Middleware

Middleware	Description
echoperm	Keeping track of users, login states and permissions.

Next

• Head over to guide
• Browse recipes

Need help?

• Hop on to chat
• Open an issue

Support Us

• ⭐ the project
• Donate
• 🌎 spread the word
• Contribute to the project

Contribute

Use issues for everything

• Report issues
• Discuss on chat before sending a pull request
• Suggest new features or enhancements
• Improve/fix documentation

Credits

• Vishal Rana - Author
• Nitin Rana - Consultant
• Contributors

License

MIT