Gin Backend Framework Cheat Sheet
A fast and usefull cheat sheet for how to use Gin.
First, what is Gin?
The fastest full-featured web framework for Go. Crystal clear.
Source: Official Gin website
Let's start. I'll write things about how to use Gin, what are important things about in and of course about the Gin Context.
Are you ready?
What is Gin Context?
Every Gin handler receives a \*gin.Context, which wraps Go’s standard context.Context along with request and response helpers. Understanding how to use the underlying context correctly is essential for building production applications that handle timeouts, cancellation, and resource cleanup properly.
I also copied it from the documentation of Gin. Source
So, as it said, Context carries everything inside it. Examples:
- Request
- Response
- URL
- Params
- Query Strings
- Body
- Header
- Functions
- And also things we put inside it to pass to the next step
Every handler has a sign like this:
func MyHandler(c *gin.Context) {
// ...
}
Remember this handler, every example is inside it.
Receive request
Here we will cover how to access data of the request. In body, url and even header.
Path Parameters
You know what is path parameters, right? If you don't know it's alright. Path parameter is a variable inside the url. For example: /api/posts/:id. See, the :id means here will be a variable. Then we can find it and use it as we need.
In Gin it's kind of very easy!
id := c.Param("id")
You can convet it to anything you want. Default is string. Convert it as UUID, Integer or what ever.
Query String
Have you seen those question marks and & signs in a url? They are query string and we can use them to get a structured data from url. Consider we want to have filter and sort. Where should we pass our data? Yaeh, in query string!
For example consider this url: /search?q=golang&page=2
q := c.Query("q")
page := c.DefaultQuery("page", "1")
We use c.Query("q") to get data of q. For now it is golang. If there be no q inside the url the result is an empty string. Just ""
But sometimes we don't need that result to be an empty string. We want if there be no result, set our default value. Look at the url again. We have page. Now it is 2 but consider there be no page at url. What should happen? PANIC!? No! We set our default value with c.DefaultQuery("page", "1"). It means give me page but if it is not set, it's alright to give me 1.
Header
Headers are variables inside every request. They can give you information and data about the client, the response and many other things. They are not in url, not in body and not in form. They are at headers part of the request.
token := c.GetHeader("Authorization")
requestID := c.GetHeader("X-Request-ID")
You should use c.GetHeader("name") to get data of a header that the key is name.
Body
The raw data that client sends. For now only we work with JSON. As an example imagine a login endpoint that client sends password and username.
{
"username": "amirhossein",
"password": "hossein_amir"
}
Alright, client sent it, Gin handled it and passed it to our handler to read it.
type CreateUserRequest struct {
Name string `json:"name" binding:"required"`
Email string `json:"email" binding:"required,email"`
}
var req CreateUserRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(400, gin.H{"error": err.Error()})
return
}
So, we created out based data with a struct. We call it CreateUserRequest. Then we create a base variable as struct and call it req. Now we need to validate it. To validate and store request body in req we use c.ShouldBindJSON. It gets out base variable. If we have error, it means something is wrong. Else we got out data!
Also we have other binds to:
c.ShouldBindQueryto bind query string.c.ShouldBindto bind auto.
Send response
Until now we understood how to get our data, parse it, change and other things. Now it's time to send out response.
JSON
The most common way in a REST API to send response is as Json.
c.JSON(
200,
gin.H{
"message": "success",
"data": user,
}
)
Ok, but how is it working?
First argument is status code. You can put integer inside it like 200 or using net/http like http.StatusOK.
Second argument is the data as json. We can use gin.H{} to put out data there. For example I sent a message and user data.
Or you can put your own struct instead of using gin.H{} like this;
c.JSON(http.StatusOK, user)
As you can see I used net/http and my own struct.
String
The function c.String only returns a string. Easy!
c.String(200, "pong")
HTML
If you want to send a HTML page use c.HTML.
c.HTML(200, "index.html", gin.H{"title": "Home"})
Data
Consider sending a buffer data using c.Data.
c.Data(200, "application/octet-stream", []byte{...})
File
Sending back file is very important in some cases. Use c.File.
c.File("/path/to/file.pdf")
Redirect
Also redirect is simple using c.Redirect. Just put your path.
c.Redirect(302, "/login")
Status
Here is something very usefull to know. Sometimes you have no content as response. Like you deleted something and want to say yes it is deleted. How!? Only send a no content status using c.Status.
c.Status(204)
Abort
Remember this part. You really should know about c.Abort.
What is abort? When we want to stop the request from going further we need to use c.Abort. Look at these 3 codes:
The only abort. Stops.
c.Abort()
return
Now we stop the request and tell client why we did that with status code.
c.AbortWithStatus(401)
return
We stoped the request, we told client why with a status code and now let's tell them why in human language.
c.AbortWithStatusJSON(403, gin.H{"error": "Forbidden"})
return
Don't forget to put return after c.Abort. IMPORTANT!
Using Context
Sometimes we have a middleware. It may authenticate use and we want to pass use data to the handler. At this section we will learn how to use Context to do that for us.
Write data to Context
This step is the middleware part and we set data using c.Set(key, value) as key-value pair.
// Middleware
c.Set("name", "Amirhossein")
Read data from Context
Next step is at the handler that wants to read data which is set at last step (middleware). We can do it with c.Get("key").
// Handler
name, exists := c.Get("name")
if !exists {
// Here means name is not exists
}
fmt.Println(name)
Middlrwares
Middlewares are functions that they run after or before handlers. We may have many middlewares between the server and the handler.
Here is a brief of how can we create a middleware.
func AuthMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
token := c.GetHeader("Authorization")
if token == "" {
// We don't have token for example and we need to abort it
c.AbortWithStatusJSON(
401, // Status code
gin.H{
"error": "Unauthorized"
}, // Json
)
return
}
// This point means everything is OK
c.Set("userID", "123") // Example of setting things in Context
c.Next() // Go to next step
}
}
To go to the next step we use c.Next. Like Js frameworks like ExpressJs.
So don't forget:
c.Next()-> Continuec.Abort()-> Break
Routing
We know what is a response, request, context and middleware in Gin. But where is the core which must run our app!?
Yes, Routing!
Routing is the part that decides which handler should run for which URL and which HTTP method.
Basic Routing
r := gin.Default()
r.GET("/ping", func(c *gin.Context) {
c.JSON(200, gin.H{"message": "pong"})
})
r.POST("/users", createUser)
r.GET("/users/:id", getUser)
gin.Default() creates a router with Logger and Recovery middleware already attached.
Grouping Routes
When you have many endpoints, grouping them makes your code much cleaner.
api := r.Group("/api")
{
api.GET("/todos", listTodos)
api.POST("/todos", createTodo)
}
// Group with middleware
admin := r.Group("/admin", AuthMiddleware())
{
admin.GET("/dashboard", dashboard)
admin.DELETE("/users/:id", deleteUser)
}
You can even nest groups:
v1 := r.Group("/api/v1")
{
todos := v1.Group("/todos")
{
todos.GET("", listTodos)
todos.POST("", createTodo)
}
}
HTTP Methods
In REST APIs we mostly use these five methods. Let’s quickly see what each one means.
GET
Used to read data. It should not change anything on the server.
r.GET("/todos", listTodos)
r.GET("/todos/:id", getTodo)
POST
Used to create a new resource or pass something in a secure way.
r.POST("/todos", createTodo)
PUT
Used to full updates. An entire resource.
When you use PUT, the client is expected to send the complete object. If a field is missing, it usually means that field should be cleared or reset.
r.PUT("/todos/:id", replaceTodo)
PATCH
Used for partial update. A part of resource.
With PATCH, the client only sends the fields that need to be changed. The rest of the resource stays untouched.
r.PATCH("/todos/:id", updateTodo)
DELETE
Used to delete a resource.
r.DELETE("/todos/:id", deleteTodo)
Conclusion
That’s it for this cheat sheet.
We covered the most important parts of Gin:
- What
gin.Contextis and why it’s so powerful. - How to read data from request (params, query, headers, body).
- How to send different kinds of responses.
- Working with middlewares.
- Routing and grouping endpoints.
- HTTP methods.
This should be enough to start building real APIs with Gin confidently.
In the next posts, I’ll write about:
- Validation in Gin.
- How to structure a clean project.
- GORM the ORM for Go.
- Authentication with JWT.
If you found this useful, feel free to share it. And if you have any questions, just drop a comment.
Thanks for reading.
Happy coding.