Skip to main content

Echo Request Body

In web applications, the request body often contains crucial data sent by clients. Whether it's a JSON payload from a mobile app, form data from a browser, or binary content like an uploaded file, understanding how to access and process request bodies is essential for any Echo developer.

Understanding HTTP Request Bodies​

The request body is the data portion of an HTTP request that follows the headers. Unlike URL parameters or query strings, the request body can contain larger and more complex data structures, making it suitable for operations like:

  • Submitting form data
  • Sending JSON objects for API requests
  • Uploading files
  • Transmitting XML documents
  • Sending raw text or binary data

Accessing the Request Body in Echo​

Echo provides several methods to access and parse the request body based on its content type. Let's explore the most common approaches:

1. Binding JSON Data​

JSON is the most popular format for API requests. Echo makes it easy to bind JSON request bodies to Go structs:

go
package main

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

// User represents the structure of our JSON data
type User struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
}

func main() {
    e := echo.New()
    
    e.POST("/users", func(c echo.Context) error {
        // Create a new User instance
        user := new(User)
        
        // Bind the request body to the user struct
        if err := c.Bind(user); err != nil {
            return echo.NewHTTPError(http.StatusBadRequest, "Invalid request payload")
        }
        
        // Process the user data...
        
        return c.JSON(http.StatusOK, map[string]interface{}{
            "message": "User created successfully",
            "user": user,
        })
    })
    
    e.Start(":8080")
}

When you send a POST request to /users with this JSON body:

json
{
    "name": "John Doe",
    "email": "[email protected]",
    "age": 30
}

Echo will automatically parse it and bind it to your User struct.

2. Handling Form Data​

For HTML forms or multipart form data, Echo provides methods to access form values:

go
e.POST("/submit-form", func(c echo.Context) error {
    // Get form values
    name := c.FormValue("name")
    email := c.FormValue("email")
    
    // Process form data...
    
    return c.String(http.StatusOK, "Form submitted: "+name+" ("+email+")")
})

For a form submission with fields name=Jane Doe and [email protected], the response would be:

Form submitted: Jane Doe ([email protected])

3. Accessing Raw Request Body​

Sometimes you might need to access the raw request body, especially when dealing with custom content types:

go
e.POST("/raw", func(c echo.Context) error {
    // Read the raw body
    body, err := io.ReadAll(c.Request().Body)
    if err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, "Error reading request body")
    }
    
    // Remember to restore the body for other middleware
    c.Request().Body = io.NopCloser(bytes.NewBuffer(body))
    
    // Process the raw body...
    
    return c.String(http.StatusOK, "Received raw body with length: "+strconv.Itoa(len(body)))
})

4. Handling File Uploads​

Echo makes file uploads straightforward:

go
e.POST("/upload", func(c echo.Context) error {
    // Get the file from the request
    file, err := c.FormFile("file")
    if err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, "No file provided")
    }
    
    // Source
    src, err := file.Open()
    if err != nil {
        return err
    }
    defer src.Close()
    
    // Destination
    dst, err := os.Create("uploads/" + file.Filename)
    if err != nil {
        return err
    }
    defer dst.Close()
    
    // Copy the file
    if _, err = io.Copy(dst, src); err != nil {
        return err
    }
    
    return c.String(http.StatusOK, "File uploaded successfully: "+file.Filename)
})

Validating Request Bodies​

Binding data is only the first step. Proper validation is crucial for maintaining application security and data integrity:

go
package main

import (
    "net/http"
    
    "github.com/labstack/echo/v4"
    "github.com/go-playground/validator/v10"
)

// User with validation tags
type User struct {
    Name  string `json:"name" validate:"required,min=3"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"required,gte=18,lte=120"`
}

// Custom validator
type CustomValidator struct {
    validator *validator.Validate
}

func (cv *CustomValidator) Validate(i interface{}) error {
    if err := cv.validator.Struct(i); err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
    }
    return nil
}

func main() {
    e := echo.New()
    e.Validator = &CustomValidator{validator: validator.New()}
    
    e.POST("/users", func(c echo.Context) error {
        user := new(User)
        
        // Bind the request body
        if err := c.Bind(user); err != nil {
            return echo.NewHTTPError(http.StatusBadRequest, "Invalid request format")
        }
        
        // Validate the data
        if err := c.Validate(user); err != nil {
            return err
        }
        
        // Process validated user...
        
        return c.JSON(http.StatusCreated, user)
    })
    
    e.Start(":8080")
}

This example adds validation to ensure the user has a valid name, email, and age before processing the data.

Real-World Example: REST API for a Blog​

Let's create a more comprehensive example with a REST API for managing blog posts:

go
package main

import (
    "net/http"
    "strconv"
    "time"
    
    "github.com/labstack/echo/v4"
    "github.com/go-playground/validator/v10"
)

// Post represents a blog post
type Post struct {
    ID        int       `json:"id"`
    Title     string    `json:"title" validate:"required,min=5"`
    Content   string    `json:"content" validate:"required,min=20"`
    Author    string    `json:"author" validate:"required"`
    Tags      []string  `json:"tags" validate:"required,min=1"`
    CreatedAt time.Time `json:"created_at"`
}

// Storage for our posts (in-memory database for example)
var posts = []Post{}
var lastID = 0

// CustomValidator for data validation
type CustomValidator struct {
    validator *validator.Validate
}

func (cv *CustomValidator) Validate(i interface{}) error {
    if err := cv.validator.Struct(i); err != nil {
        return echo.NewHTTPError(http.StatusBadRequest, err.Error())
    }
    return nil
}

func main() {
    e := echo.New()
    e.Validator = &CustomValidator{validator: validator.New()}
    
    // Create a new post
    e.POST("/posts", func(c echo.Context) error {
        post := new(Post)
        
        // Bind the request body
        if err := c.Bind(post); err != nil {
            return echo.NewHTTPError(http.StatusBadRequest, "Invalid post format")
        }
        
        // Validate the data
        if err := c.Validate(post); err != nil {
            return err
        }
        
        // Set metadata
        lastID++
        post.ID = lastID
        post.CreatedAt = time.Now()
        
        // Save the post
        posts = append(posts, *post)
        
        return c.JSON(http.StatusCreated, post)
    })
    
    // Get all posts
    e.GET("/posts", func(c echo.Context) error {
        return c.JSON(http.StatusOK, posts)
    })
    
    // Update a post
    e.PUT("/posts/:id", func(c echo.Context) error {
        id, _ := strconv.Atoi(c.Param("id"))
        
        // Find the post
        index := -1
        for i, p := range posts {
            if p.ID == id {
                index = i
                break
            }
        }
        
        if index == -1 {
            return echo.NewHTTPError(http.StatusNotFound, "Post not found")
        }
        
        // Get the updated post
        updatedPost := new(Post)
        if err := c.Bind(updatedPost); err != nil {
            return echo.NewHTTPError(http.StatusBadRequest, "Invalid post format")
        }
        
        // Validate the data
        if err := c.Validate(updatedPost); err != nil {
            return err
        }
        
        // Preserve metadata
        updatedPost.ID = posts[index].ID
        updatedPost.CreatedAt = posts[index].CreatedAt
        
        // Update the post
        posts[index] = *updatedPost
        
        return c.JSON(http.StatusOK, updatedPost)
    })
    
    e.Start(":8080")
}

This example demonstrates a complete flow of:

  1. Creating posts with validated request bodies
  2. Reading posts (although this doesn't use request bodies)
  3. Updating posts with request bodies

Best Practices for Handling Request Bodies​

  1. Always validate input: Never trust client-supplied data without validation.
  2. Set proper content type expectations: Use middleware to ensure requests have appropriate Content-Type headers.
  3. Handle large payloads carefully: Set maximum body size limits to prevent DOS attacks.
  4. Use appropriate binding methods: Choose the right Echo method based on the content type.
  5. Return clear error messages: When binding or validation fails, provide informative errors.
go
// Example of setting body size limit middleware
e.Use(middleware.BodyLimit("2M")) // Limit request body to 2MB

// Example of requiring specific content types
e.POST("/api/json", handleJSONEndpoint, middleware.ContentType("application/json"))

Common Pitfalls and Solutions​

Reading the Body Multiple Times​

Once the request body is read, it can't be read again unless you restore it:

go
// Solution: Store and restore the body
bodyBytes, _ := io.ReadAll(c.Request().Body)
c.Request().Body = io.NopCloser(bytes.NewBuffer(bodyBytes))

Large File Uploads​

For large file uploads, stream the data instead of loading it all into memory:

go
e.POST("/large-upload", func(c echo.Context) error {
    // Get the file from the request
    file, err := c.FormFile("file")
    if err != nil {
        return err
    }
    
    src, err := file.Open()
    if err != nil {
        return err
    }
    defer src.Close()
    
    dst, err := os.Create("large-files/" + file.Filename)
    if err != nil {
        return err
    }
    defer dst.Close()
    
    // Stream the file with a buffer
    buf := make([]byte, 1024)
    for {
        n, err := src.Read(buf)
        if err != nil && err != io.EOF {
            return err
        }
        if n == 0 {
            break
        }
        
        if _, err := dst.Write(buf[:n]); err != nil {
            return err
        }
    }
    
    return c.String(http.StatusOK, "Large file uploaded successfully")
})

Summary​

Working with request bodies in Echo is straightforward thanks to its expressive API and helper methods. We've covered:

  • Binding JSON data to Go structs
  • Processing form data and file uploads
  • Accessing the raw request body
  • Validating request data with custom validators
  • Building a real-world REST API that handles various request bodies
  • Best practices and common pitfalls

By mastering request body handling, you'll be able to build robust Echo applications that can accept and process a wide variety of client data.

Additional Resources​

Exercises​

  1. Create an Echo endpoint that accepts a JSON array of products and validates each product in the array.
  2. Build a file upload system that accepts multiple files and validates their types and sizes.
  3. Implement a custom binding function that can handle both JSON and XML requests to the same endpoint.
  4. Create a middleware that logs request bodies (be careful with sensitive data and large bodies).
  5. Build an endpoint that can accept different content types (JSON, XML, form data) and process them appropriately.

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)