Golang Base64 Encoding Examples with Best Practices

In Go, this tutorial will explore the diverse world of Base64 encoding. In this case you will know how to encode and decode various data types including URLs, strings, images, files among others to ensure safe transmission over the internet. We are going to look at encoding JSON objects, compact data representation by removing padding and encoding complex structures like structs, UTF-8 texts, maps and byte arrays. Throughout every section are practical examples that can be employed in different scenarios and enable you make effective use of Base64 encodings in your Golang projects.

 

Encode and Decode URLs

When one needs to convert characters so they can be transmitted on the Internet without any ambiguity in Golang one would encode them as URLS. The net/url package provides a function QueryEscape for percent encoding URL parameters which replaces unsafe ASCII characters with a % sign followed by two hexadecimal digits.

For example, this demonstrates how to encode URLs containing special characters (&).

import (
    "fmt"
    "net/url"
)

func main() {
    originalURL := "https://example.com/search?query=Golang Tips & Tricks"
    encodedURL := url.QueryEscape(originalURL)
    fmt.Println(encodedURL)
}

Decoding is simply reversing the process; converting back percent-encoded characters into their original form. This is very common when you have received URL parameters on your server-side end that should be interpreted correctly. For decoding purposes it makes use of QueryUnescape function located in the net/url package.

func main() {
    encodedURL := "https%3A%2F%2Fexample.com%2Fsearch%3Fquery%3DGolang+Tips+%26+Tricks"
    decodedURL, err := url.QueryUnescape(encodedURL)
    if err != nil {
        fmt.Println("Error decoding URL:", err)
    }
    fmt.Println(decodedURL)
}

This example decodes an encoded URL back to its original form that converts %3A,%2F etc…into /,:,and & respectively making the url readable and usable again.

 

Basic String Encoding and Decoding

There is a process where the original string data is converted to Base64 encoded string which represents the binary data of the original string in text form using some specific ASCII characters. Conversely, when decoded it converts back to its initial representation.

package main

import (
	"encoding/base64"
	"fmt"
)

func main() {
	originalString := "Hello, world!"
	encodedString := base64.StdEncoding.EncodeToString([]byte(originalString))
	fmt.Println("Encoded:", encodedString) // Output: Encoded: SGVsbG8sIHdvcmxkIQ==

	decodedBytes, err := base64.StdEncoding.DecodeString(encodedString)
	if err != nil {
		fmt.Println("Error decoding string:", err)
		return
	}
	decodedString := string(decodedBytes)
	fmt.Println("Decoded:", decodedString) //Output: Decoded: Hello, world!
}

 

Converting Images to Base64

A good practice, particularly for web development is to encode images into Base64 in Golang and embed them in HTML or CSS files. This way, a page’s load time may be shortened by reducing the number of HTTP requests made while small images or icons can be directly put on your HTML or CSS file thus making them part of your code.

To go through it; read the image file, encode its binary data as a Base64 string, then use this string within an html img tag or css background property.

package main

import (
    "encoding/base64"
    "fmt"
    "io/ioutil"
)

func main() {
    // Read the image file
    imgData, err := ioutil.ReadFile("path/to/your/image.jpg")
    if err != nil {
        fmt.Println("Error reading image file:", err)
        return
    }

    // Encode the image to Base64
    encodedImg := base64.StdEncoding.EncodeToString(imgData)
    fmt.Println("Encoded Image:", encodedImg)

    // This encoded string can then be embedded directly into HTML or CSS
}

Embedding in HTML:

<img src="data:image/jpeg;base64,{{encodedImg}}" />

Embedding in CSS:

.background {
    background-image: url('data:image/jpeg;base64,{{encodedImg}}');
}

Replace {{encodedImg}} with the actual Base64 string obtained from the encoding process.

 

Encoding Binary Files

Golang has an effective way of encoding files in Base64. This helps especially when you have to send them through media that cannot handle binary data, like email attachments or for certain types of data storage where binary data is not natively supported. Binary files, such as images, PDFs and executables , contain information that can not be read by humans. When one wants to transmit these files over a text-based protocol (e.g., HTTP, SMTP for emails) or save them on a text only system; the binary information is converted into ASCII string format that can be safely-transmitted or stored using Base64 encoding.

package main

import (
    "encoding/base64"
    "fmt"
    "io/ioutil"
)

func main() {
    // Load the binary file
    binaryData, err := ioutil.ReadFile("path/to/binary/file")
    if err != nil {
        fmt.Println("Error loading file:", err)
        return
    }

    // Encode to Base64
    encodedString := base64.StdEncoding.EncodeToString(binaryData)
    fmt.Println("Encoded to Base64:", encodedString)
}

 

Encoding JSON Objects for web APIs

Web developers require a means of encoding JSON objects for web APIs as well as serializing and encoding JSON strings in Golang when developing web applications and services. It is this way that allows complicated data structures to be sent over the internet using a lightweight text format that can be easily parsed by different clients and servers.

Before you send a Go struct via an API, you must serialize it to a JSON string. The purpose of this process is served by the Marshal function from the encoding/json package.

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

user := User{Name: "John Doe", Email: "john@example.com"}
jsonData, err := json.Marshal(user)
if err != nil {
    log.Println("Error serializing user:", err)
}
fmt.Println(string(jsonData))

This snippet of code transforms User struct into a JSON string.
When working with complex data structures involving nested structs or arrays, serialization stays the same. Serializing them into nested JSON format is automatically done by json.Marshal function which also handles nested structures and arrays.

In many cases, rather than first converting into a string, we encode JSON data directly on an HTTP response writer for web APIs. This can be accomplished using json.NewEncoder.

http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
    user := User{Name: "Jane Doe", Email: "jane@example.com"}
    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(user)
})

It encodes the User struct as JSON directly into the HTTP response.

In scenarios where direct JSON transmission may not be supported in certain environments like URLs, you can use Base64 encoding.

jsonData := `{"name":"John Doe","email":"john@example.com"}`
encodedData := base64.StdEncoding.EncodeToString([]byte(jsonData))

In case you are including JSON directly to URL parameters then URL encoding might be more appropriate.

encodedURL := url.QueryEscape(jsonData)

The JSON data will need to be decoded or unmarshaled back into the original data structures upon receipt. This will involve using json.Unmarshal for JSON strings and json.NewDecoder for direct decoding from HTTP requests or other streams.

 

Base64 Encoding without Padding

Base64 encoding transforms binary data into text through a 64 character set. It is meant to make sure the transfer of binary data is secure for instance by email or URLs that only support text. The padding is made by = in Base64 coding in order to ensure that the encoded data comes out as multiple of four bytes because it works on 24 bits blocks from the original data.

However, in some cases padding might not be desirable such as if space is limited or if one is encoding URL link or any other situation where byte size of the encoded string does matter. Using WithPadding function, Golang can encode and decode Base64 data without padding characters.

In order to achieve no padding while encoding, you can use StdEncoding.WithPadding(base64.NoPadding) to build an encoder that does not append any kind of padding character.

package main

import (
    "encoding/base64"
    "fmt"
)

func main() {
    data := "Hello, world!"
    encoding := base64.StdEncoding.WithPadding(base64.NoPadding)
    encodedData := encoding.EncodeToString([]byte(data))
    fmt.Println("Encoded without padding:", encodedData) // Output: Encoded without padding: SGVsbG8sIHdvcmxkIQ
}

The decoding process in itself is quite straightforward and there’s no need to specify “no padding” while doing so since information indicating absence of pad bits can always be derived from the encoded message directly.

decodedData, err := encoding.DecodeString(encodedData)
if err != nil {
    fmt.Println("Error decoding:", err)
    return
}
fmt.Println("Decoded data:", string(decodedData)) // Output: Decoded data: Hello, world!

If you want to encode and decode without using any paddings, you must also ensure that your Base64 version (standard or URL-safe) remains consistent throughout and understand that not all decoders may accept unpadded base 64 data gracefully especially those used in other languages/servers.

 

Serializing structs to JSON or binary format.

The process of converting Golang struct into Base64 encoding is a two-step operation. The first part involves serialization of the struct to either binary or JSON format before involving the encoded form in a base64. This method is very effective when transmitting complicated data structures over channels that primarily convey text or whenever these structures have to be kept in an actual state for ease of usage among different systems.

package main

import (
    "encoding/json"
    "log"
)

type MyStruct struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    myStruct := MyStruct{Name: "John Doe", Age: 30}
    serializedData, err := json.Marshal(myStruct)
    if err != nil {
        log.Fatal("Error serializing struct:", err)
    }
    // serializedData is now a []byte of JSON data
}

Once you possess the serialized data, you can encode it using encoding/base64 package as base64. Consequently, this step makes a conversion between binary or text data and a bese-64 string which can be easily transmitted through text-based protocols or saved to texts readable by human beings.

package main

import (
    "encoding/base64"
    "encoding/json"
    "fmt"
    "log"
)

type MyStruct struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    myStruct := MyStruct{Name: "John Doe", Age: 30}
    serializedData, err := json.Marshal(myStruct)
    if err != nil {
        log.Fatal("Error serializing struct:", err)
    }
    
    encodedData := base64.StdEncoding.EncodeToString(serializedData)
    fmt.Println("Base64 Encoded:", encodedData)
}

It allows easy submission of complex structured data across network connections, embedding within HTML or XML documents, and storing in databases and files where text data are often preferred. Moreover, decoding the original structure back from Base64 string is just like reversing the process — decode from Base64 to get serialized data and unmarshal that data again into an original structure.

 

Encoding UTF-8 strings to handle multilingual data

Encoding a UTF-8 string to Base64 in Golang does not differ from encoding any other string because Go natively supports UTF-8. The following is a simple example:

package main

import (
    "encoding/base64"
    "fmt"
)

func main() {
    originalText := "こんにちは世界" // "Hello, World" in Japanese
    encodedText := base64.StdEncoding.EncodeToString([]byte(originalText))
    fmt.Println("Encoded UTF-8 String:", encodedText) // Output: Encoded UTF-8 String: 44GT44KT44Gr44Gh44Gv5LiW55WM
}

Reversing the process of converting a String to Base64 is easy. One only needs to change the base64 value into bytes and eventually cast it again into a string making sure Go will do with its own UTF-8 coding.

decodedBytes, err := base64.StdEncoding.DecodeString(encodedText)
if err != nil {
    fmt.Println("Error decoding Base64:", err)
    return
}
decodedText := string(decodedBytes)
fmt.Println("Decoded UTF-8 String:", decodedText) // Output: Decoded UTF-8 String: こんにちは世界

 

Encoding Map Data Structures

The normal way to serialize map data structures for Base64 encoding is by using JSON serialization. This will entail transferring the map into JSON strings which could be converted into Base64. For instance, this technique can be useful for spreading around configuration data or settings across different parts of an application, or even between applications themselves.

package main

import (
    "encoding/base64"
    "encoding/json"
    "fmt"
)

func main() {
    myMap := map[string]interface{}{
        "apiKey": "123456789",
        "user":   "gopher",
    }
    
    // Serialize map to JSON
    jsonData, err := json.Marshal(myMap)
    if err != nil {
        fmt.Println("Error serializing map:", err)
        return
    }
    
    // Encode JSON to Base64
    encodedData := base64.StdEncoding.EncodeToString(jsonData)
    fmt.Println("Encoded Base64 String:", encodedData) // Output: Encoded Base64 String: eyJhcGlLZXkiOiIxMjM0NTY3ODkiLCJ1c2VyIjoiZ29waGVyIn0=
}

 

Encoding and decoding byte arrays

In Golang, when you encoding byte arrays, they are converted into text using Base64 encoding. This process is important if you want to send binary data over a medium that requires only textual information such as JSON in web APIs or any other way of holding data that is easily readable and portable.

package main

import (
	"encoding/base64"
	"fmt"
)

func main() {
	// Example binary data
	binaryData := []byte{0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x20, 0x77, 0x6f, 0x72, 0x6c, 0x64, 0x21}

	// Encoding binary data to Base64
	encodedString := base64.StdEncoding.EncodeToString(binaryData)
	fmt.Println("Encoded Base64 String:", encodedString) // Output: Encoded Base64 String: SGVsbG8gd29ybGQh
}

Decoding in the other hand is the reverse process where encoded Base64 text content is transformed back into its original binary form. This happens a lot when one receives Base 64 encoded data which has to be displayed in its initial format or be worked upon.

encodedString := "SGVsbG8gd29ybGQh" // Base64 for "Hello world!"

// Decoding Base64 string to binary data
decodedData, err := base64.StdEncoding.DecodeString(encodedString)
if err != nil {
    fmt.Println("Error decoding Base64 string:", err)
    return
}
fmt.Println("Decoded Binary Data:", decodedData)

 

Frequently Asked Questions

 

Conclusion

The guide has thus far journeyed through the basics of Golang Base64 encoding by exposing how it becomes useful when dealing with various string manipulations, images, files, and JSON complexities. The golang’s encoding/base64 package has been discovered as an important tool in data handling for web development and beyond. Always remember that Base64 encoding is about keeping the correctness and mobility of information even though it does not provide any security. Use these lessons in your future Golang projects to achieve a delicate balance between secure encryption and data representation when working on sensitive areas.

 

Further Resources

Go Official Documentation - encoding/base64