Building robust and efficient web services is a core task for many developers. While a plethora of frameworks exist to simplify this, there’s immense value in understanding the foundational mechanics. For those venturing into Go backend development, crafting an API without external dependencies offers a unique learning experience.
When I set out to build a web service in Go, I wanted to keep it simple. After getting comfortable with Go’s basics, I challenged myself to create a simple RESTful API server from scratch. I decided not to use any frameworks — just Go’s standard net/http library — and to store data in memory rather than a database (just for simplicity to showcase it in this guide). Go is fast and efficient (it compiles to a single small binary and has strong concurrency support).
In this article, I’ll share what I learned about setting up routes, following RESTful principles, using an in-memory data store, and handling concurrency with a mutex, all essential for building a simple REST API in Go.
Mastering RESTful Design and Routing with `net/http`
Before diving into code, understanding the “why” behind RESTful API design is crucial. It sets the stage for creating intuitive and predictable services.
What does “RESTful” actually mean? Before coding, I made sure I understood the basics of RESTful API design. REST stands for Representational State Transfer, and it’s a style for designing networked applications. In a RESTful API, you treat server data as resources and use standard HTTP methods to operate on them. For example, you use GET to read data, POST to create data, PUT/PATCH to update, and DELETE to remove. Each resource is identified by a unique URL (often using nouns like /people or /people/123), and servers typically exchange data in a lightweight format like JSON. Another key principle is statelessness — each request from a client should contain all the information needed, so the server doesn’t keep track of client state between requests. These principles make APIs predictable and easy to use.
For my project, I established a “person” resource, defining clear endpoints to perform CRUD (Create, Read, Update, Delete) operations. This approach ensures logical interaction with the API.
Each operation corresponds to an HTTP method and endpoint:
POST /person — add a new person GET /person?id=123 — get one person by ID (I used a query parameter for simplicity) GET /persons — get all people PUT /person?id=123 — update an existing person DELETE /person?id=123 — delete a person
Importantly, each handler in my server checks the request method and returns an HTTP 405 “Method Not Allowed” if the method is wrong for that endpoint (for example, a GET request sent to the /person creation endpoint). Using proper methods and status codes is part of being RESTful and helps avoid confusion.
Go’s Standard Library for Efficient Routing
Setting up Routing with Go’s net/http package Go makes it straightforward to handle routes and requests using the net/http package. There’s a global HTTP request multiplexer (router) that you can use via http.HandleFunc, or you can create your own http.ServeMux. For this small project, I used the default and simply registered my endpoints with handler functions. Each handler is just a Go function with the signature func(w http.ResponseWriter, r *http.Request).
Here’s how I hooked up my routes in the main() function:
http.HandleFunc("/person", addPerson)
http.HandleFunc("/person/get", getPerson)
http.HandleFunc("/persons", getAllPersons)
http.HandleFunc("/person/update", updatePerson)
http.HandleFunc("/person/delete", deletePerson) log.Println("Server running at http://localhost:8080")
log.Fatal(http.ListenAndServe(":8080", nil))
Each call to http.HandleFunc ties a URL path to a handler function. When a request comes in matching that path, Go’s HTTP server will invoke the corresponding function. In the code above, I set up five endpoints (as described earlier) and then start the server on port 8080. The http.ListenAndServe(“:8080”, nil) call begins listening for requests; it uses nil which means it will use the default mux where we registered our handlers. This call is blocking (it will run indefinitely until the program is stopped), and if the server fails to start, log.Fatal will print the error and exit.
Storing Data & Handling Concurrency in Go
For a learning project, abstracting away database complexities allows focus on the core API logic. An in-memory store simplifies data management significantly.
Utilizing an In-Memory Data Store
Using an In-Memory Data Store (for now) For storing data on the server, I chose to use an in-memory map rather than a database. This was purely for simplicity and learning purposes. I defined a struct type to represent a Person in our system:
type Person struct { ID int `json:"id"` Name string `json:"name"` Email string `json:"email"`
}
This struct has tags like json:”name” so that when we encode it to JSON, the fields come out in lowercase as expected by JSON clients. To hold the data, I declared a package-level variable db as a map from int to Person, and another variable idCounter to generate unique IDs for new records.
This map `db` acts as a fake database. It’s a quick way to store data in memory and retrieve it by ID. The obvious downside is that the data won’t persist if the server restarts (and it’s not shared across multiple servers), but for a toy app or initial development, an in-memory store is extremely easy to work with. (Of course, in a production application, you’d use a proper database like Postgres or MongoDB instead of a single server map!).
Safeguarding Data with Mutexes for Concurrency
Handling Concurrency with a Mutex One thing to be mindful of: as soon as you allow concurrent requests (and Go’s HTTP server does handle requests concurrently by default), you have to protect shared data. In our case, the db map and idCounter are shared between all requests. Without precautions, two clients creating people at the same time could try to update idCounter and the map concurrently, leading to a race condition or corrupted data.
Go’s solution is to use a sync.Mutex to lock critical sections. A mutex (mutual exclusion lock) ensures that only one goroutine can access the protected section at a time. I added a `mu sync.Mutex` variable alongside the `db` map. Then in each handler, I lock the mutex before reading or writing the map, and unlock it afterward.
For example, in the `addPerson` handler, once I decode the request JSON into a Person struct, I do:
mu.Lock() p.ID = id Counterdb[p.ID] = p // write to the map idCounter++ mu.Unlock()
The rule of thumb is: any shared variable that any goroutine might write to should be protected for all accesses (reads or writes). Go’s net/http server runs each request handler in its own goroutine, so without a lock, concurrent map access would eventually cause a crash or wrong behavior (the Go runtime will detect a concurrent map write and panic).
Implementing CRUD Operations and Testing Your Go API
With the routing and data storage foundations in place, implementing the API’s core functionality becomes straightforward. Go’s standard library provides powerful tools for common web service tasks.
Streamlined CRUD Implementation
With the groundwork done (routes, data store, and locking), I implemented the actual logic for each endpoint: Create, Read, Read All, Update, and Delete. Each handler leverages Go’s standard library for efficient JSON encoding/decoding and error handling.
The key takeaway is that Go’s simplicity shines here — reading JSON into a struct is one line (json.NewDecoder(r.Body).Decode(&p)), writing JSON out is one line (json.NewEncoder(w).Encode(data)), and error handling is straightforward with http.Error for sending error messages and status codes. The standard library gave me everything I needed to build a fully functional API.
Testing Your Server
Running and Testing the Server To run the server, I simply execute the Go program (go run main.go or compile and run the binary). The server logs a message that it’s running on localhost:8080. I used `curl` and a tool like Postman to test each endpoint:
Create:
curl -X POST -H "Content-Type: application/json" \ -d '{"name":"Alice","email":"alice@example.com"}' \ http://localhost:8080/person Get one:
curl "http://localhost:8080/person/get?id=1" Get all:
curl http://localhost:8080/persons Update:
curl -X PUT -H "Content-Type: application/json" \ -d '{"name":"Alice Smith","email":"alice.smith@example.com"}' \ "http://localhost:8080/person/update?id=1" Delete:
curl -X DELETE "http://localhost:8080/person/delete?id=1"
I was able to verify that each endpoint behaved as expected. For instance, trying to fetch a non-existent ID returned my custom “Person not found” message with a 404 status, and the server correctly handled concurrent requests without issues (thanks to the mutex).
Key Lessons for Building Go Web Services
This project underscored several best practices for efficient and reliable Go web services, especially when building a simple REST API.
Use the right HTTP method and status codes — Designing around REST principles makes your API intuitive. Following HTTP conventions is a big part of building a clean API. Keep handlers simple and focused — Each handler should do one thing. This separation makes the code easier to test and maintain.
Guard shared data with locks (or other sync tools) — Go’s concurrency is powerful, but you must avoid data races. Any state that persists beyond a single request needs protection. In our case a sync.Mutex was the easiest solution.
Use the standard library to its fullest — It’s impressive how much you can do without any external packages. This project was a great way to understand those before potentially moving to frameworks. Go makes concurrency easy… but you’re responsible for protecting data. I won’t forget to consider thread safety in future projects.
Starting simple is okay. Using an in-memory map and dummy data is fine for a learning project. It kept me focused on the core — handling HTTP requests — without the complexity of database setup. I understand that for real applications I’ll swap the map for a database and perhaps use a router framework for more features. But now I have a clear picture of what those tools are abstracting.
Go’s standard library is powerful. I was able to go from nothing to a working web API without installing anything else. This project gave me confidence that I can implement web services in Go and that I understand the basics of how things works under the hood.
Conclusion
Building a simple RESTful API in Go has been a rewarding step in my journey as a Go developer. Not only do I have a small web service running, but I also gained practical experience with REST principles, the net/http package, and concurrency control.
This mini project has shown me that building a web API in Go is very achievable, even for a beginner. Going forward, I plan to explore more — maybe connecting this service to a real database, adding user authentication, or writing tests for my handlers. If you’re looking to dive into Go API development, starting without frameworks is an excellent way to grasp the fundamentals. Happy coding!
