Quick answer
Gin is a web framework for Go that turns a handful of routes into a working JSON API with almost no boilerplate. This post builds a small orders API with it: list orders, create an order, and fetch one order by id, with real requests and real responses.
A small online shop in Karachi takes orders through a chat app, and the owner copies each one into a spreadsheet by hand, until two customers order the same last kurta and both get a yes. The owner needs a small API: a list of orders anyone on the team can read, a way to add one, and a way to fetch one by number. Just three endpoints that answer in JSON. Go fits: it compiles to one binary and starts fast, and Gin keeps the routing and JSON work to a few lines. This post builds exactly that API and breaks it once, so you see what a bad request looks like.
What I would check before using it
My first check is whether the API is small enough for Gin to stay simple. Three endpoints, JSON in and JSON out, is exactly where Gin shines: one file, one router, three handlers. If the project needs HTML pages, sessions, and an admin panel, look at a bigger framework. The Go Explained: Simple Code That Runs Fast post covers the language underneath.
My second check is the Go version. Gin v1.12.0 needs Go 1.25 or later, and the demo ran on Go 1.25.0. An older toolchain refuses to build it. Check go version first.
My third check is how the API handles bad input. Gin binds JSON into a Go struct and validates it with struct tags, but the default error messages are written for developers, not for API users. The demo returns those messages as they are, which is fine for learning. For a real client, translate them into a short message naming the field.
My fourth check is where the data lives. The demo keeps orders in a slice in memory, so every restart wipes the shop. That is fine for learning, and the wrong design for a shop that takes real money. Decide early whether the next step is a database; a demo that forgets is not a service that remembers.
My verdict, as judgement: adopt Gin when you want a small, fast JSON API in Go and the team is comfortable with the language. Skip it when the project needs a full-featured framework, or when the team does not write Go. The recommendation flips the moment the API grows past simple CRUD.
Three orders, one API, and a wrong total
Three orders belong to one small shop: Ayesha buys a kurta and a dupatta for Rs 12,400, Bilal buys sneakers for Rs 7,800, and Hina buys a handbag and a wallet for Rs 5,400. The first two are seeded; Hina's arrives through the API.
One file holds the whole API: the Order struct carries json tags for the field names and binding tags so a missing field fails validation, three handlers cover the three routes, and gin.Default() adds logging and panic recovery.
// Orders API for The Practical Developer (Gin demo).
//
// A small online shop exposes three endpoints with Gin:
// GET /orders list all orders
// POST /orders create an order (JSON body, all fields required)
// GET /orders/:id fetch one order by id
//
// Run from this folder:
// go run main.go (listens on http://localhost:8080)
// curl http://localhost:8080/orders
package main
import (
"net/http"
"strconv"
"github.com/gin-gonic/gin"
)
type Order struct {
ID int `json:"id"`
Customer string `json:"customer" binding:"required"`
Items []string `json:"items" binding:"required"`
Total float64 `json:"total" binding:"required"`
}
var orders = []Order{
{ID: 101, Customer: "Ayesha", Items: []string{"kurta", "dupatta"}, Total: 12400},
{ID: 102, Customer: "Bilal", Items: []string{"sneakers"}, Total: 7800},
}
var nextID = 103
func listOrders(c *gin.Context) {
c.JSON(http.StatusOK, orders)
}
func getOrder(c *gin.Context) {
id, err := strconv.Atoi(c.Param("id"))
if err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "order id must be a number"})
return
}
for _, order := range orders {
if order.ID == id {
c.JSON(http.StatusOK, order)
return
}
}
c.JSON(http.StatusNotFound, gin.H{"error": "order not found"})
}
func createOrder(c *gin.Context) {
var order Order
if err := c.ShouldBindJSON(&order); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
order.ID = nextID
nextID++
orders = append(orders, order)
c.JSON(http.StatusCreated, order)
}
func main() {
gin.SetMode(gin.ReleaseMode)
router := gin.Default()
router.GET("/orders", listOrders)
router.GET("/orders/:id", getOrder)
router.POST("/orders", createOrder)
router.Run(":8080")
}
Here is the real output: the list returns the two seeded orders, creating Hina's order returns it with id 103, and fetching order 101 returns Ayesha's order alone. The server log agrees.
$ go run main.go
$ curl http://localhost:8080/orders
[{"id":101,"customer":"Ayesha","items":["kurta","dupatta"],"total":12400},{"id":102,"customer":"Bilal","items":["sneakers"],"total":7800}]
$ curl -X POST http://localhost:8080/orders -H 'Content-Type: application/json' -d '{"customer":"Hina","items":["handbag","wallet"],"total":5400}'
{"id":103,"customer":"Hina","items":["handbag","wallet"],"total":5400}
$ curl http://localhost:8080/orders/101
{"id":101,"customer":"Ayesha","items":["kurta","dupatta"],"total":12400}
[GIN] 2026/11/19 - 03:05:22 | 200 | 81.272µs | ::1 | GET "/orders"
[GIN] 2026/11/19 - 03:05:22 | 201 | 211.888µs | ::1 | POST "/orders"
[GIN] 2026/11/19 - 03:05:22 | 200 | 61.141µs | ::1 | GET "/orders/101"
Hina's order goes wrong twice. First, the total is missing, so the required tag fires and Gin answers 400. Then it arrives as the text "5400" instead of the number 5400, and Go's decoder refuses it because the struct field is a float64. Neither request touches the orders list: bad data is rejected at the door, not stored and discovered later.
$ curl -X POST http://localhost:8080/orders -H 'Content-Type: application/json' -d '{"customer":"Hina","items":["handbag","wallet"]}'
{"error":"Key: 'Order.Total' Error:Field validation for 'Total' failed on the 'required' tag"}
$ curl -X POST http://localhost:8080/orders -H 'Content-Type: application/json' -d '{"customer":"Hina","items":["handbag","wallet"],"total":"5400"}'
{"error":"json: cannot unmarshal string into Go struct field Order.total of type float64"}
The fix is on the client side: send every field, and send numbers as numbers. The server side already handles it: ShouldBindJSON returns the error to the handler, so the handler shapes the response. The Node.js REST API post builds the same three endpoints in JavaScript, where a missing field slips through unless you check for it, and the FastAPI post shows Python doing the same validation with Pydantic.
Common mistakes and how to fix them
First, using BindJSON when you want to control the error. The symptom is a plain-text 400 written by Gin itself, with no JSON body to parse. The fix is ShouldBindJSON, as the demo uses: it returns the error, and the handler decides the response.
Second, sending numbers as strings in JSON. The symptom is json: cannot unmarshal string into Go struct field Order.total of type float64, for a request that looks right at a glance. The fix is to send 5400, not "5400": Go types the field as a number, and JSON must match.
Third, reading the wrong path parameter name. The symptom is a 400 saying the order id must be a number, even for /orders/101. The fix is to match them: the route says /orders/:id, so the handler must call c.Param("id"), not c.Param("orderId").
Fourth, trusting the in-memory slice with real data. The symptom is orders that vanish after a restart, because the slice is rebuilt from seed data on every start. The fix is to store orders in a database; the slice is a demo only.
Frequently Asked Questions
Is Gin part of Go itself? No. Gin is a third-party module, github.com/gin-gonic/gin, added with go get like any other dependency. Go's standard library serves HTTP on its own; Gin adds routing, binding, and middleware.
Do I need to know Go well before trying Gin? Basic Go is enough: structs, slices, functions, and error handling. If main.go reads clearly, you are ready; the Go Explained post fills in the language basics.
How is Gin different from the standard library net/http package? The standard library gives you a server and a handler, and you write the routing and JSON parsing yourself. Gin adds a router, JSON binding with validation, and middleware, so the same API takes less code.
Does Gin work with a database? Gin does not care where the data lives. The demo handlers read a slice, and the same handlers can query Postgres or SQLite instead. The framework handles HTTP; storage stays your choice.
What to remember
- Gin maps a route to a handler in one line.
- Struct tags declare the JSON shape and validation rules together.
- ShouldBindJSON returns the error to your handler.
- Numbers in JSON must be numbers: "5400" is text, and Go refuses it.
- The in-memory slice is for learning; real orders need a database.
Where this leaves you
Gin earns its place the moment you want a JSON API in Go without writing your own router and JSON checks by hand. The demo proved what matters: the API listed, created, and fetched real orders, bad data was rejected with a clear 400 instead of stored, and the whole server fit in one file of about eighty lines. Start with three endpoints and an in-memory list, add a database when the orders matter, and keep the binding tags honest so bad requests fail loudly at the door.
Further reading
- Gin docs, https://gin-gonic.com/docs/
- Gin docs, model binding and validation, https://gin-gonic.com/en/docs/binding/binding-and-validation/
- Go tutorial, Developing a RESTful API with Go and Gin, https://go.dev/doc/tutorial/web-service-gin
- Go Explained: Simple Code That Runs Fast, https://practicaldevblog.blogspot.com/2026/10/go-explained-simple-code-that-runs-fast.html
- Build Your First REST API With Node.js and Express, https://practicaldevblog.blogspot.com/2026/10/build-your-first-rest-api-with-nodejs.html
- FastAPI Explained: Python APIs at Full Speed, https://practicaldevblog.blogspot.com/2026/10/fastapi-explained-python-apis-at-full.html
- Hono: One Small API That Runs Almost Anywhere, https://practicaldevblog.blogspot.com/2026/11/hono-one-small-api-that-runs-almost.html
Waqas Shahid is a software engineer from Karachi with more than 12 years of experience, including 6+ years in engineering leadership. He writes The Practical Developer.
Top comments (0)