How to Create a Web Server in Go using Gin (Golang)
This article covers how to create a simple Web server in Go using the Gin framework.
This article covers how to create a simple Web server in Go using the Gin framework.
These instructions were written for a Mac. But they should easily translate to instructions for Linux or Windows.
Step 1. Setup your development environment
This article assumes that you've already installed Go. If not, see the setup instructions in my previous article.
Step 2. Create a new project folder
At the command line create and/or browse to a folder where you keep your projects:
- Add a new project folder
- On a Mac I do it like this:
mkdir go-server
cd go-server
Step 3: Initialize the Go project
On the command line, adjust this command for your git service and username:
go mod init github.com/mitchallen/go-server
You should see a response similar to this:
go: creating new go.mod: module github.com/mitchallen/go-server
On a Mac you can verify the file was created doing this:
ls -ls
cat go.mod
You should see something like this:
module github.com/mitchallen/go-server
go 1.20
Step 4. Install the Gin framework
From the root of your project folder, run this command to install the Gin framework:
go get -u github.com/gin-gonic/gin
Step 5. Create a source file
Create an empty file to update in later steps:
On a Mac you can do it like this:
touch server.go
Step 6. Edit server.go
Using your favorite code editor, paste this code into server.go and save it:
This code creates a new Gin router instance using gin.Default()
. It then sets up a route that responds to GET requests to the root path ("/") by returning a JSON response with a "message" key and the value "Hello, world!". Finally, it starts the web server and listens on port 8080.
As you will see in the next step, you can override the default port using an environment variable when you run the server.
Step 7. Run the server
In a command or terminal window do the following:
- Change to the folder where your server.go file is if you aren't there already
- Run this command:
PORT=8085 go run server.go
The command runs the server, but sets the PORT to 8085, overriding the default port. This makes it easy to change ports if you have a conflict on your machine.
Step 8. Test the server
You can test the server in a browser, like Chrome that will return the JSON response.
- Browse to: http://localhost:8085/
- You should get back a JSON response in the browser window, like this:
{"message":"Hello, world!"}
If you have curl installed, you can also test it like this in a second terminal window:
curl http://localhost:8085/
Step 9. Creating Routes and Handling Requests
To create more complex routes and handle requests, you can use the r.GET
, r.POST
, r.PUT
, and r.DELETE
methods to set up routes for different HTTP methods. You can then add a function as the second argument to each method to handle the request.
For example, to create a route that responds to GET requests to "/users" and returns a JSON response with a list of users, you can add the following code above the r.Run() statement:
- Stop the server using Ctrl-C in the terminal window
- Save server.go
- Run the server again
To test from a second terminal window, run this curl command with the modified path:
curl http://localhost:8085/users
You should get a response like this:
{"users":["Alice","Bob","Charlie"]}
Step 10. Add a Post Request Handler
Similarly, to handle POST requests to "/users" and create a new user, we can add the following code:
This code defines a new struct called user
that has Name
and Email
fields. You can then use c.BindJSON
to parse the JSON request body and populate the user
struct with the values. If there is an error parsing the JSON, return a 400 error response. Otherwise, create the user in the database (which we haven't implemented yet, because that's beyond the scope of this article), and return a 201 response with a "message" key.
Test it using this curl command:
curl -X POST http://localhost:8085/users \
-H "Content-Type: application/json" \
-d '{"name":"John Doe","email":"johndoe@example.com"}'
You should get a response like this:
{"message":"User created"}
Let's break down the command:
-X POST
specifies that we want to perform a POST request-H "Content-Type: application/json"
sets theContent-Type
header toapplication/json
, indicating that we are sending JSON data in the request body-d '{"name": "John Doe", "email": "johndoe@example.com"}'
specifies the data to be sent in the request body as a JSON payloadhttp://localhost:8085/users
is the URL of the API endpoint we want to send the POST request to
After running this command, curl
will send the POST request to http://localhost:8085/users
with the JSON payload, and display the response from the server.
Conclusion
In this article, you learned how to:
- Install the Gin Web server framework package for Go
- Create and run a simple Web server in Go
- Test the Web server using curl and a browser
- Add an HTTP GET url handler
- Add an HTTP POST url handler
- How to test a POST handler using curl
Recommended Reading
- Concurrency in Go: Tools and Techniques for Developers
- Go Programming Language, The (Addison-Wesley Professional Computing Series)