Skip to main content

Gin XML Responses

In modern web applications, serving data in various formats is crucial. While JSON has become the dominant format for most APIs, XML remains important, especially when working with legacy systems, SOAP services, or specific client requirements. Gin, a high-performance web framework for Go, provides excellent support for generating XML responses.

This guide will walk you through working with XML responses in Gin applications, from basic implementation to more advanced techniques.

Introduction to XML Responses in Gin​

XML (eXtensible Markup Language) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. When building APIs or web services, you might need to provide data in XML format to meet specific client requirements.

Gin makes it easy to return XML responses through its context object, which offers the XML() method specifically for this purpose. This method handles:

  • Converting Go structs to XML format
  • Setting appropriate Content-Type headers
  • Sending the response to the client

Basic XML Response​

Let's start with a simple example to demonstrate how to return an XML response in Gin:

go
package main

import (
    "github.com/gin-gonic/gin"
)

// Product represents product information
type Product struct {
    ID     string  `xml:"id"`
    Name   string  `xml:"name"`
    Price  float64 `xml:"price"`
    InStock bool   `xml:"in_stock"`
}

func main() {
    router := gin.Default()
    
    // Route that returns a product as XML
    router.GET("/product", func(c *gin.Context) {
        product := Product{
            ID:     "p1001",
            Name:   "Ergonomic Keyboard",
            Price:  79.99,
            InStock: true,
        }
        
        c.XML(200, product)
    })
    
    router.Run(":8080")
}

When you run this server and make a GET request to /product, the response will be:

xml
<Product>
  <id>p1001</id>
  <name>Ergonomic Keyboard</name>
  <price>79.99</price>
  <in_stock>true</in_stock>
</Product>

The response will also have the Content-Type header set to application/xml; charset=utf-8.

XML Struct Tags​

XML serialization in Go is controlled by struct tags. These tags allow you to customize how fields are represented in the XML output.

go
type User struct {
    Username  string `xml:"username"`            // Simple element
    Email     string `xml:"email,attr"`          // Attribute
    Age       int    `xml:"age,omitempty"`       // Omit if empty
    Address   string `xml:"contact>address"`     // Nested element
    CreatedAt string `xml:"-"`                   // Ignored field
}

Let's see how this struct would be serialized:

go
router.GET("/user", func(c *gin.Context) {
    user := User{
        Username:  "johndoe",
        Email:     "[email protected]",
        Age:       30,
        Address:   "123 Main St",
        CreatedAt: "2023-01-01",
    }
    
    c.XML(200, user)
})

The response would be:

xml
<User email="[email protected]">
  <username>johndoe</username>
  <age>30</age>
  <contact>
    <address>123 Main St</address>
  </contact>
</User>

Notice how:

  • Email is rendered as an attribute
  • CreatedAt is excluded completely
  • Address is nested inside a contact element
  • Age is included because it has a value (if it was 0, it would be omitted due to the omitempty tag)

Custom XML Root Elements​

By default, Gin uses the struct name as the XML root element. However, you might want to customize this. You can use a wrapper struct or the XMLName field for this purpose:

go
type ProductResponse struct {
    XMLName xml.Name `xml:"product_response"`
    Product Product  `xml:"product"`
    Status  string   `xml:"status"`
}

router.GET("/product/custom", func(c *gin.Context) {
    response := ProductResponse{
        Product: Product{
            ID:      "p1001",
            Name:    "Ergonomic Keyboard",
            Price:   79.99,
            InStock: true,
        },
        Status: "success",
    }
    
    c.XML(200, response)
})

The response would be:

xml
<product_response>
  <product>
    <id>p1001</id>
    <name>Ergonomic Keyboard</name>
    <price>79.99</price>
    <in_stock>true</in_stock>
  </product>
  <status>success</status>
</product_response>

Working with Collections​

When returning collections of items in XML, you can structure them using slices and appropriate struct tags:

go
type ProductList struct {
    XMLName  xml.Name  `xml:"product_catalog"`
    Products []Product `xml:"products>product"`
}

router.GET("/products", func(c *gin.Context) {
    productList := ProductList{
        Products: []Product{
            {ID: "p1001", Name: "Ergonomic Keyboard", Price: 79.99, InStock: true},
            {ID: "p1002", Name: "Wireless Mouse", Price: 49.99, InStock: true},
            {ID: "p1003", Name: "4K Monitor", Price: 299.99, InStock: false},
        },
    }
    
    c.XML(200, productList)
})

The response would be:

xml
<product_catalog>
  <products>
    <product>
      <id>p1001</id>
      <name>Ergonomic Keyboard</name>
      <price>79.99</price>
      <in_stock>true</in_stock>
    </product>
    <product>
      <id>p1002</id>
      <name>Wireless Mouse</name>
      <price>49.99</price>
      <in_stock>true</in_stock>
    </product>
    <product>
      <id>p1003</id>
      <name>4K Monitor</name>
      <price>299.99</price>
      <in_stock>false</in_stock>
    </product>
  </products>
</product_catalog>

XML IndentedOutput​

By default, Gin sends compact XML without indentation. For debugging purposes, you might want to enable indented (pretty-printed) XML:

go
// Set Gin to output indented XML globally
gin.SetMode(gin.DebugMode)

// OR use XMLIndented for a specific response
router.GET("/product/pretty", func(c *gin.Context) {
    product := Product{
        ID:      "p1001",
        Name:    "Ergonomic Keyboard",
        Price:   79.99,
        InStock: true,
    }
    
    c.IndentedXML(200, product)
})

Note that indented XML adds overhead and should typically be avoided in production environments.

Error Handling with XML Responses​

For consistent API responses, you might want to standardize your error messages in XML format:

go
type ErrorResponse struct {
    XMLName xml.Name `xml:"error"`
    Code    int      `xml:"code"`
    Message string   `xml:"message"`
}

router.GET("/product/:id", func(c *gin.Context) {
    id := c.Param("id")
    
    // Simulate a product lookup
    if id != "p1001" {
        // Return a structured error response
        errorResponse := ErrorResponse{
            Code:    404,
            Message: "Product not found",
        }
        c.XML(404, errorResponse)
        return
    }
    
    // Return the product if found
    product := Product{
        ID:      id,
        Name:    "Ergonomic Keyboard",
        Price:   79.99,
        InStock: true,
    }
    c.XML(200, product)
})

When requesting a non-existent product, the client would receive:

xml
<error>
  <code>404</code>
  <message>Product not found</message>
</error>

Using XML and Other Response Formats​

Gin supports content negotiation, allowing clients to specify which format they prefer. You can use c.Negotiate to handle multiple response formats:

go
router.GET("/product/negotiate/:id", func(c *gin.Context) {
    product := Product{
        ID:      c.Param("id"),
        Name:    "Ergonomic Keyboard",
        Price:   79.99,
        InStock: true,
    }
    
    c.Negotiate(200, gin.Negotiate{
        Offered: []string{gin.MIMEJSON, gin.MIMEXML},
        Data:    product,
    })
})

This allows clients to specify their preferred format using the Accept header:

  • Accept: application/xml - Will return XML
  • Accept: application/json - Will return JSON

Real-World Example: Product API​

Let's look at a more complete example of a Product API with XML responses:

go
package main

import (
    "encoding/xml"
    "github.com/gin-gonic/gin"
    "net/http"
)

// Product struct with XML tags
type Product struct {
    ID          string  `xml:"id,attr"`
    Name        string  `xml:"name"`
    Description string  `xml:"description,omitempty"`
    Price       float64 `xml:"price"`
    InStock     bool    `xml:"in_stock"`
    Category    string  `xml:"category"`
}

// ProductResponse wraps a product with a standard response format
type ProductResponse struct {
    XMLName   xml.Name `xml:"response"`
    Success   bool     `xml:"success,attr"`
    Product   *Product `xml:"product,omitempty"`
    Error     string   `xml:"error,omitempty"`
    Timestamp string   `xml:"timestamp"`
}

// ProductList handles collections of products
type ProductList struct {
    XMLName  xml.Name  `xml:"product_catalog"`
    Count    int       `xml:"count,attr"`
    Products []Product `xml:"products>product"`
}

// In-memory product database for demo
var productDB = map[string]Product{
    "p001": {ID: "p001", Name: "Laptop", Description: "High-end developer laptop", Price: 1299.99, InStock: true, Category: "Electronics"},
    "p002": {ID: "p002", Name: "Coffee Mug", Description: "Ceramic mug", Price: 12.99, InStock: true, Category: "Kitchen"},
    "p003": {ID: "p003", Name: "Headphones", Description: "Noise-cancelling", Price: 199.99, InStock: false, Category: "Electronics"},
}

func main() {
    router := gin.Default()
    
    // Get all products
    router.GET("/products", func(c *gin.Context) {
        products := make([]Product, 0, len(productDB))
        for _, p := range productDB {
            products = append(products, p)
        }
        
        response := ProductList{
            Count:    len(products),
            Products: products,
        }
        
        c.XML(http.StatusOK, response)
    })
    
    // Get a specific product
    router.GET("/products/:id", func(c *gin.Context) {
        id := c.Param("id")
        
        product, exists := productDB[id]
        
        response := ProductResponse{
            Success:   exists,
            Timestamp: "2023-05-10T15:04:05Z", // In a real app, use the current time
        }
        
        if exists {
            response.Product = &product
            c.XML(http.StatusOK, response)
        } else {
            response.Error = "Product not found"
            c.XML(http.StatusNotFound, response)
        }
    })
    
    router.Run(":8080")
}

When requesting a specific product, you'd get:

xml
<response success="true" timestamp="2023-05-10T15:04:05Z">
  <product id="p001">
    <name>Laptop</name>
    <description>High-end developer laptop</description>
    <price>1299.99</price>
    <in_stock>true</in_stock>
    <category>Electronics</category>
  </product>
</response>

And when requesting a non-existent product:

xml
<response success="false" timestamp="2023-05-10T15:04:05Z">
  <error>Product not found</error>
</response>

Performance Considerations​

When working with XML responses in Gin, keep these performance tips in mind:

  1. Avoid indented XML in production - Pretty-printed XML takes more CPU time to generate and results in larger responses.

  2. Use appropriate caching - For responses that don't change often, consider implementing HTTP caching headers.

  3. Consider compression - Enable Gzip compression for XML responses, especially for larger payloads.

  4. Be mindful of struct tags - Well-designed XML struct tags can result in cleaner, smaller responses.

Summary​

In this guide, you've learned how to:

  • Return basic XML responses from a Gin application
  • Use struct tags to customize XML output
  • Create custom root elements
  • Work with collections of items
  • Handle errors with structured XML
  • Support content negotiation for multiple formats
  • Build a real-world API with XML responses

XML may not be as popular as JSON for modern APIs, but Gin's excellent XML support makes it straightforward to provide XML responses when needed. By following the patterns and best practices outlined in this guide, you can create maintainable, efficient XML APIs using Gin.

Exercises​

To reinforce what you've learned, try these exercises:

  1. Create an XML API endpoint that returns a nested object structure, such as an order with line items.
  2. Implement content negotiation that supports XML, JSON, and YAML formats.
  3. Add XML validation to ensure that incoming XML requests conform to an expected structure.
  4. Create a middleware that logs all XML responses in a compact format for debugging purposes.
  5. Build an XML endpoint that fetches data from a database and transforms it into a properly structured XML response.

Additional Resources​

By mastering XML responses in Gin, you've added a valuable skill to your toolkit for building flexible, interoperable web services.


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