Building a Simple REST API in Go Without Frameworks

When I set out to build a web service in Go, I wanted to keep it simple. 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. simple RESTful API server 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. RESTful API design Representational State Transfer resources GET POST PUT/PATCH DELETE statelessness In practice, this meant designing clear endpoints and using the right HTTP methods. For my project, I chose to create a “person” resource as an example. The API would allow clients to create a new person, retrieve one or all persons, update a person’s info, or delete a person. Each operation corresponds to an HTTP method and endpoint: In practice, this meant designing clear endpoints and using the right HTTP methods. 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 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 (In a fully RESTful design, you might use URLs like /person/123 instead of query parameters. But the idea is the same: the URL identifies the resource, and the HTTP verb tells the action.) (In a fully RESTful design, you might use URLs like /person/123 instead of query parameters. But the idea is the same: the URL identifies the resource, and the HTTP verb tells the action.) 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. 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). net/http 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)) 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. A quick note on routing: The standard library’s router matches paths literally or with a simple prefix mechanism. In my case, I used distinct paths for each action (including /person/get, /person/update, etc.) to keep it simple. This isn’t the only way to design routes — one could use path parameters or a third-party router for more complex patterns — but it worked for this mini project. A quick note on routing: 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: in-memory map type Person struct { ID int `json:"id"` Name string `json:"name"` Email string `json:"email"` } 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. For example: var ( db = make(map[int]Person) idCounter = 1 ) var ( db = make(map[int]Person) idCounter = 1 ) 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. In fact, using a simple map let me avoid setup of a real database while learning the basics. Many beginner tutorials use this approach to simulate a database . It’s blazing fast and perfectly fine for small demos. (Of course, in a production application, you’d use a proper database like Postgres or MongoDB instead of a single server map!) (Of course, in a production application, you’d use a proper database like Postgres or MongoDB instead of a single server map!) 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: sync.Mutex addPerson mu.Lock() p.ID = id Counterdb[p.ID] = p // write to the map idCounter++ mu.Unlock() mu.Lock() p.ID = id Counterdb[p.ID] = p // write to the map idCounter++ mu.Unlock() By locking around these operations, I ensure that no two requests can interleave these steps and cause inconsistent state. The same goes for reading: for instance, in a “get person” handler, I lock the mutex while retrieving from the map, then unlock once I have the result. This might seem unnecessary just for reading, but in Go even reads must be locked if there are any concurrent writes . 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). any Using a mutex in this simple project taught me about thread safety in Go. It’s a low-level detail but crucial. The good news is that this locking overhead is negligible for a small number of requests, and it keeps our data safe. Again, for a real application, a database often handles concurrency internally, or one might use more advanced patterns (like concurrent maps or channels), but a basic mutex is straightforward and effective. Implementing the CRUD Endpoints With the groundwork done (routes, data store, and locking), I implemented the actual logic for each endpoint: Create (POST /person): Read the JSON body of the request into a Person struct. Assign it a new ID (using idCounter), lock the mutex and save it in the map, then unlock. Finally, return the created person as JSON with a 201 Created status. Read (GET /person?id=X): Check the id query parameter, convert it to an integer, then lock and retrieve the person from the map. If found, return it as JSON. If no such ID, return a 404 Not Found error. Read All (GET /persons): Lock and loop through the map to collect all people into a slice, unlock, and return that slice as JSON. Update (PUT /person?id=X): Parse the id from query params, decode JSON from request body for the updated data, then lock and check if the person exists. If not, return 404. If yes, update the record (keeping the same ID) in the map and unlock. Return the updated record as JSON. Delete (DELETE /person?id=X): Parse the id, lock the map and delete the entry if it exists, then unlock. If no such person, return 404. If deletion was successful, return a simple confirmation message. Create (POST /person): Read the JSON body of the request into a Person struct. Assign it a new ID (using idCounter), lock the mutex and save it in the map, then unlock. Finally, return the created person as JSON with a 201 Created status. Create (POST /person): Read (GET /person?id=X): Check the id query parameter, convert it to an integer, then lock and retrieve the person from the map. If found, return it as JSON. If no such ID, return a 404 Not Found error. Read (GET /person?id=X): Read All (GET /persons): Lock and loop through the map to collect all people into a slice, unlock, and return that slice as JSON. Read All (GET /persons): Update (PUT /person?id=X): Parse the id from query params, decode JSON from request body for the updated data, then lock and check if the person exists. If not, return 404. If yes, update the record (keeping the same ID) in the map and unlock. Return the updated record as JSON. Update (PUT /person?id=X): Delete (DELETE /person?id=X): Parse the id, lock the map and delete the entry if it exists, then unlock. If no such person, return 404. If deletion was successful, return a simple confirmation message. Delete (DELETE /person?id=X): Each handler first validates that the HTTP method is correct (this is done by checking r.Method against the expected method). This way, if someone accidentally sends the wrong type of request (e.g., a GET to the create endpoint), we return an appropriate 405 error instead of trying to process it . Additionally, I set the Content-Type: application/json header on responses that contain JSON, so clients know how to parse the data. I won’t list the full code for all handlers here, but the pattern is similar for each. 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. 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: curl Create: Create: Create: curl -X POST -H "Content-Type: application/json"\\ -d '{"name":"Alice","email":"alice@example.com"}' \\ curl -X POST -H "Content-Type: application/json"\\ -d '{"name":"Alice","email":"alice@example.com"}' \\ This should return a JSON with Alice’s data and an assigned id (e.g. {“id”:1,”name”:”Alice”,”email”:”alice@example.com”}). Get one: This should return a JSON with Alice’s data and an assigned id (e.g. {“id”:1,”name”:”Alice”,”email”:”alice@example.com”}). id”:1,”name”:”Alice”,”email”:”alice@example.com Get one: Get one: curl " " curl " " This should return Alice’s data if the ID exists, or a 404 error if not. Get all: This should return Alice’s data if the ID exists, or a 404 error if not. Get all: Get all: curl curl Returns a list of all people in the map (in JSON array format). Update: Returns a list of all people in the map (in JSON array format). Update: Update: curl -X PUT -H "Content-Type: application/json" \\ -d '{"name":"Alice Smith","email":"alice.smith@example.com"}' \\ curl -X PUT -H "Content-Type: application/json" \\ -d '{"name":"Alice Smith","email":"alice.smith@example.com"}' \\ This modifies Alice’s name/email and returns the updated JSON. Delete: This modifies Alice’s name/email and returns the updated JSON. Delete: Delete: curl -X DELETE "http://localhost:8080/person/delete?id=1" curl -X DELETE "http://localhost:8080/person/delete?id=1" This deletes the person with ID 1, returning a confirmation message or 404 if not found. This deletes the person with ID 1, returning a confirmation message or 404 if not found. 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). Best Practices I’m Learning Through this project, I picked up some best practices for Go web services: Use the right HTTP method and status codes — Designing around REST principles makes your API intuitive. GET for reads, POST for creates, etc., and respond with proper HTTP status codes (200 OK, 201 Created, 404 Not Found, 405 Method Not Allowed, etc.) so clients know what happened. Following HTTP conventions is a big part of building a clean API . Keep handlers simple and focused — Each handler should do one thing (create, fetch, update, or delete). This separation makes the code easier to test and maintain. For example, my addPerson function doesn’t need to know anything about how the other handlers work — it just handles creation. 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 (like the in-memory map in this server) needs protection . In our case a sync.Mutex was the easiest solution. It might feel low-level, but it prevents subtle bugs. Use the standard library to its fullest — It’s impressive how much you can do without any external packages. JSON encoding/decoding, HTTP routing, and even basic data storage (maps) are all built-in. This project was a great way to understand those before potentially moving to frameworks. As a beginner, it’s tempting to grab a big library, but I found a lot of value in first learning how things work under the hood. Use the right HTTP method and status codes — Designing around REST principles makes your API intuitive. GET for reads, POST for creates, etc., and respond with proper HTTP status codes (200 OK, 201 Created, 404 Not Found, 405 Method Not Allowed, etc.) so clients know what happened. Following HTTP conventions is a big part of building a clean API . Use the right HTTP method and status codes Keep handlers simple and focused — Each handler should do one thing (create, fetch, update, or delete). This separation makes the code easier to test and maintain. For example, my addPerson function doesn’t need to know anything about how the other handlers work — it just handles creation. Keep handlers simple and focused 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 (like the in-memory map in this server) needs protection . In our case a sync.Mutex was the easiest solution. It might feel low-level, but it prevents subtle bugs. Guard shared data with locks (or other sync tools) Use the standard library to its fullest — It’s impressive how much you can do without any external packages. JSON encoding/decoding, HTTP routing, and even basic data storage (maps) are all built-in. This project was a great way to understand those before potentially moving to frameworks. As a beginner, it’s tempting to grab a big library, but I found a lot of value in first learning how things work under the hood. Use the standard library to its fullest Lessons from the “Mini REST” project Working on this mini REST server solidified a few concepts for me: Go makes concurrency easy… but you’re responsible for protecting data. The fact that net/http spins up a goroutine per request means high throughput out of the box, but also means you must handle synchronization for any shared state . I won’t forget to consider thread safety in future projects. RESTful design isn’t too hard once you grasp it. It’s basically about resources and standard operations. Planning the endpoints first (with proper methods and paths) helped guide my implementation. It also made the API predictable to use. This exercise reinforced why following REST conventions is beneficial . 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. As one resource put it, this kind of in-memory setup is fine for demos, but real projects should use a proper DB once you move beyond the toy stage . 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 work under the hood. Frameworks and libraries can still help (for routing, validation, etc.), but it’s great to know the fundamentals. Go makes concurrency easy… but you’re responsible for protecting data. The fact that net/http spins up a goroutine per request means high throughput out of the box, but also means you must handle synchronization for any shared state . I won’t forget to consider thread safety in future projects. Go makes concurrency easy… must RESTful design isn’t too hard once you grasp it. It’s basically about resources and standard operations. Planning the endpoints first (with proper methods and paths) helped guide my implementation. It also made the API predictable to use. This exercise reinforced why following REST conventions is beneficial . RESTful design 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. As one resource put it, this kind of in-memory setup is fine for demos, but real projects should use a proper DB once you move beyond the toy stage . Starting simple is okay. 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 work under the hood. Frameworks and libraries can still help (for routing, validation, etc.), but it’s great to know the fundamentals. Go’s standard library is powerful. 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. Going forward, I plan to explore more — maybe connecting this service to a real database, adding user authentication, or writing tests for my handlers. But as a starting point, this mini project has shown me that building a web API in Go is very achievable, even for a beginner. I’ll continue sharing what I learn as I delve deeper into Go for backend development! Sources: Sources: DIY Golang Web Server: No Dependencies Needed! by Flo Woelki net/http Go documentation DIY Golang Web Server: No Dependencies Needed! by Flo Woelki DIY Golang Web Server: No Dependencies Needed! by Flo Woelki net/http Go documentation net/http Go documentation