REST APIs | Building Web Services Tutorial

Go Programming: Building Web Services - REST APIs

This document outlines the basics of building REST APIs in Go. We'll cover the core concepts, a simple example, and best practices.

1. Core Concepts

REST (Representational State Transfer): An architectural style for designing networked applications. Key principles include:
- Client-Server: Separation of concerns.
- Stateless: Each request from client to server must contain all the information needed to understand the request. No client context is stored on the server between requests.
- Cacheable: Responses should be labeled as cacheable or not.
- Layered System: Client doesn't necessarily know if it's connecting directly to the end server or to an intermediary.
- Uniform Interface: The most important principle. It defines how clients interact with resources. This includes:
  - Resource Identification: Resources are identified by URIs (Uniform Resource Identifiers).
  - Resource Manipulation through Representations: Clients manipulate resources using representations (e.g., JSON, XML).
  - Self-Descriptive Messages: Messages contain enough information to understand how to process them.
  - Hypermedia as the Engine of Application State (HATEOAS): Responses include links to related resources, allowing clients to discover the API.
HTTP Methods: Used to define the operation to be performed on a resource.
- GET: Retrieve a resource.
- POST: Create a new resource.
- PUT: Update an entire resource.
- PATCH: Partially update a resource.
- DELETE: Delete a resource.
JSON (JavaScript Object Notation): A lightweight data-interchange format commonly used in REST APIs.

2. Setting up the Project

Create a project directory:
```
mkdir go-rest-api
cd go-rest-api
```
Initialize a Go module:
```
go mod init go-rest-api
```
Install necessary packages:
```
go get github.com/gorilla/mux
```
(Mux is a popular routing library for Go)

3. A Simple Example: Task API

Let's build a simple API to manage tasks. Each task will have an ID, a title, and a completed status.

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"

	"github.com/gorilla/mux"
)

// Task struct
type Task struct {
	ID        int    `json:"id"`
	Title     string `json:"title"`
	Completed bool   `json:"completed"`
}

// Tasks slice to store tasks in memory (for simplicity)
var tasks []Task

// Get all tasks
func getTasks(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(tasks)
}

// Get a single task by ID
func getTask(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	params := mux.Vars(r)
	id := params["id"]

	for _, task := range tasks {
		if fmt.Sprintf("%d", task.ID) == id {
			json.NewEncoder(w).Encode(task)
			return
		}
	}

	http.Error(w, "Task not found", http.StatusNotFound)
}

// Create a new task
func createTask(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	var newTask Task
	json.NewDecoder(r.Body).Decode(&newTask)

	newTask.ID = len(tasks) + 1
	tasks = append(tasks, newTask)

	json.NewEncoder(w).Encode(newTask)
}

// Update a task
func updateTask(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	params := mux.Vars(r)
	id := params["id"]

	var updatedTask Task
	json.NewDecoder(r.Body).Decode(&updatedTask)

	for i, task := range tasks {
		if fmt.Sprintf("%d", task.ID) == id {
			updatedTask.ID = task.ID // Keep the original ID
			tasks[i] = updatedTask
			json.NewEncoder(w).Encode(updatedTask)
			return
		}
	}

	http.Error(w, "Task not found", http.StatusNotFound)
}

// Delete a task
func deleteTask(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	params := mux.Vars(r)
	id := params["id"]

	for i, task := range tasks {
		if fmt.Sprintf("%d", task.ID) == id {
			tasks = append(tasks[:i], tasks[i+1:]...)
			json.NewEncoder(w).Encode(map[string]string{"message": "Task deleted"})
			return
		}
	}

	http.Error(w, "Task not found", http.StatusNotFound)
}

func main() {
	router := mux.NewRouter()

	// Define routes
	router.HandleFunc("/tasks", getTasks).Methods("GET")
	router.HandleFunc("/tasks/{id}", getTask).Methods("GET")
	router.HandleFunc("/tasks", createTask).Methods("POST")
	router.HandleFunc("/tasks/{id}", updateTask).Methods("PUT")
	router.HandleFunc("/tasks/{id}", deleteTask).Methods("DELETE")

	// Start the server
	log.Fatal(http.ListenAndServe(":8000", router))
}

Explanation:

Task struct: Defines the structure of a task. The json:"..." tags are used for JSON serialization/deserialization.
tasks slice: A simple in-memory store for tasks. In a real application, you'd use a database.
getTasks, getTask, createTask, updateTask, deleteTask functions: These functions handle the different HTTP methods and perform the corresponding operations on the tasks.
mux.NewRouter(): Creates a new router using the gorilla/mux library.
router.HandleFunc(...): Defines the routes and associates them with the corresponding handler functions. .Methods(...) specifies the allowed HTTP methods for each route.
http.ListenAndServe(":8000", router): Starts the server and listens for requests on port 8000.

4. Running the Example

Save the code: Save the code as main.go.
Run the application:
```
go run main.go
```

Test the API: You can use tools like curl, Postman, or httpie to test the API.

Get all tasks:
```
curl http://localhost:8000/tasks
```

Create a new task:

curl -X POST -H "Content-Type: application/json" -d '{"title": "Buy groceries", "completed": false}' http://localhost:8000/tasks

Get a specific task (e.g., ID 1):
```
curl http://localhost:8000/tasks/1
```

Update a task (e.g., ID 1):

curl -X PUT -H "Content-Type: application/json" -d '{"id": 1, "title": "Buy groceries", "completed": true}' http://localhost:8000/tasks/1

Delete a task (e.g., ID 1):

curl -X DELETE http://localhost:8000/tasks/1

5. Best Practices

Error Handling: Implement robust error handling. Return appropriate HTTP status codes and informative error messages.
Input Validation: Validate all input data to prevent security vulnerabilities and ensure data integrity.
Data Serialization/Deserialization: Use a library like encoding/json for handling JSON data.
Database Integration: Use a database (e.g., PostgreSQL, MySQL, MongoDB) to store data persistently. Consider using an ORM (Object-Relational Mapper) like GORM to simplify database interactions.
Middleware: Use middleware for common tasks like logging, authentication, and authorization.
Testing: Write unit tests and integration tests to ensure the API is working correctly.
Documentation: Document your API using tools