Crie sua Primeira API REST com Go (Guia Prático para Iniciantes 2025)

Aprenda a criar uma API REST funcional com Go (Golang) do zero. Um guia passo a passo para iniciantes usando apenas a biblioteca padrão net/http.

Nos últimos artigos, nós mergulhamos em conceitos poderosos. Desvendamos os superpoderes de engenharia do recursos do Go e entendemos o que é uma API, o sistema circulatório da internet.

Agora, é hora de unir esses dois mundos.

A pergunta que separa a teoria da prática é: como transformar as ideias em um servidor real, que recebe requisições e devolve dados pela internet? Muitos iniciantes pensam que para isso precisam de frameworks complexos e centenas de linhas de código.

A beleza do Go, como vimos, é sua filosofia de simplicidade e sua incrível biblioteca padrão.

Neste guia prático, “mão na massa”, vamos construir juntos sua primeira API REST funcional em Go. Do zero. Sem frameworks externos, usando apenas o que a linguagem já oferece nativamente. E o melhor: você terá tudo rodando no seu computador em menos de 20 minutos.

Mindset Chave: O Poder do “Suficientemente Bom”

Nosso objetivo hoje não é construir a API da Netflix. É entender os blocos de construção fundamentais de qualquer API: receber um pedido (request) e enviar uma resposta (response). Vamos criar um servidor simples, mas funcional. Essa base é o ponto de partida de TODAS as grandes aplicações back-end. Foco no progresso, não na perfeição.

Construindo a API, Passo a Passo

1. Pré-requisitos: A Bancada de Trabalho

Primeiro, garanta que você tem o Go instalado e configurado no seu sistema. Se precisar de ajuda, siga o guia oficial de instalação no site oficial de download do Go.

Agora, crie uma pasta para o nosso projeto (ex: minha-primeira-api) e, dentro dela, crie um arquivo chamado main.go. É aqui que toda a nossa mágica vai acontecer.

2. A Estrutura Básica: Ligando o Servidor

Vamos começar com o mínimo necessário para ter um servidor web rodando. Abra o main.go e cole o seguinte código:

package main

import (
	"fmt"
	"net/http"
)

// Este é um "handler", uma função que lida com requisições.
func homePage(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Bem-vindo à minha primeira API com Go!")
}

func main() {
	// Dizemos ao Go que a função homePage deve responder na rota "/"
	http.HandleFunc("/", homePage)

	// Ligamos o servidor na porta 8080.
	// O 'nil' significa que estamos usando o multiplexador padrão do Go.
	fmt.Println("Servidor escutando na porta 8080...")
	http.ListenAndServe(":8080", nil)
}

Para rodar: Abra seu terminal, navegue até a pasta do projeto e execute go run main.go. Agora, abra seu navegador e acesse http://localhost:8080. Você deverá ver a nossa mensagem de boas-vindas!

3. Definindo Nossos Dados

Uma API serve dados. Vamos criar uma estrutura para representar livros e alguns dados de exemplo. Adicione o seguinte código ao seu main.go:

// ... (acima do package main)
import (
	"encoding/json" // Precisaremos deste pacote para converter nossos dados para JSON
	"fmt"
	"net/http"
)

// 'struct' é como definimos um tipo de objeto em Go
type Livro struct {
	ID    string `json:"id"`
	Titulo string `json:"titulo"`
	Autor  string `json:"autor"`
}

// Vamos criar alguns dados de exemplo
var livros = []Livro{
	{ID: "1", Titulo: "A Arte da Guerra", Autor: "Sun Tzu"},
	{ID: "2", Titulo: "O Príncipe", Autor: "Maquiavel"},
}
// ... (o resto do código continua)

4. Criando nosso Primeiro “Endpoint” (/livros)

Um “endpoint” é simplesmente uma URL onde sua API responde. Vamos criar um que devolve nossa lista de livros em formato JSON.

Crie uma nova função handler e atualize a função main:

// ... (após a função homePage)
func obterLivros(w http.ResponseWriter, r *http.Request) {
	// Definimos o tipo de conteúdo da resposta como JSON
	w.Header().Set("Content-Type", "application/json")
	// Convertemos nossa lista de livros para JSON e a enviamos como resposta
	json.NewEncoder(w).Encode(livros)
}

func main() {
	http.HandleFunc("/", homePage)
	// Novo endpoint para nossa lista de livros
	http.HandleFunc("/livros", obterLivros)

	fmt.Println("Servidor escutando na porta 8080...")
	http.ListenAndServe(":8080", nil)
}

5. Testando a API Completa

Pare o servidor anterior no terminal (com Ctrl + C) e rode novamente: go run main.go.

Agora, acesse a nova URL no seu navegador: http://localhost:8080/livros.

O resultado deverá ser um belo JSON com a lista dos nossos dois livros. Parabéns, você acabou de criar e consumir sua primeira API REST com Go!

Sabedoria do Especialista: A Regra do Tratamento de Erros

Nossa API é simples, mas em uma aplicação real, muitas coisas podem dar errado (o banco de dados pode falhar, o JSON pode ser inválido, etc.). A marca de um bom desenvolvedor Go é o tratamento explícito de erros. A função json.NewEncoder(w).Encode(livros) na verdade retorna um erro. Em um código de produção, você sempre deve verificá-lo: err := json.NewEncoder(w).Encode(livros) if err != nil { // Lidar com o erro aqui }

FAQ: Próximos Passos

• 1. E se eu quiser buscar um livro específico (ex: /livros/1)?
  • Você precisaria de um roteador mais avançado para extrair o ID da URL ou usar um framework. É um ótimo próximo passo para estudar!
• 2. Preciso de um framework como Gin ou Echo?
  • Para APIs complexas, frameworks como o Gin Gonic ou site do Echo simplificam muito o roteamento, middlewares e validação. Mas entender o pacote net/http primeiro, como fizemos hoje, é fundamental.
• 3. Como eu conecto isso a um banco de dados real?
  • Você usaria um pacote de driver de banco de dados para Go (ex: para PostgreSQL ou MySQL). Em vez de ler da nossa lista de exemplo livros, sua função obterLivros faria uma consulta ao banco de dados.

Conclusão: O Poder em Suas Mãos

Parabéns! Você foi além da teoria e construiu um servidor web funcional, uma API REST de verdade, usando apenas o poder nativo do Go. Você entendeu na prática o ciclo de uma requisição HTTP, como estruturar dados com structs e como servi-los em formato JSON.

Este pequeno projeto é a semente de qualquer grande sistema back-end. A lógica para servir uma lista de livros é a mesma para servir uma lista de usuários, produtos ou vídeos. Você agora tem o conhecimento fundamental para construir a espinha dorsal de aplicações web complexas.