Mastering RESTful API Design in Go: 12 Essential Best Practices

This article revisits RESTful API best practices with Go Web, providing a concise checklist for building clean and consistent APIs.

1. Use JSON

Both request and response payloads should use JSON because it is lightweight, readable, and easily maps to Go structs. The Gin framework simplifies binding JSON to models with c.BindJSON and returning JSON with c.JSON. For file uploads, FormData is more efficient than embedding files in JSON.

func HandleLogin(c *gin.Context) {
    param := &LoginParams{}
    if err := c.BindJSON(param); err != nil {
        c.JSON(http.StatusBadRequest, &Resp{Error: "parameters error"})
        return
    }
    // validation ...
    session := sessions.Default(c)
    session.Set(sessionsKey, param.UserID)
    session.Save()
    c.JSON(http.StatusOK, &Resp{Data: "login succeed"})
}

2. Do Not Put Verbs in Paths

HTTP methods already express actions (GET, POST, PUT, DELETE), so resource URLs should contain only nouns.

3. Use Plural Nouns for Resources

Resource collections such as articles should be plural to reflect the underlying database table.

4. Hierarchical Resources for Sub‑entities

Comments belong to articles and can be nested under the article path, e.g., /articles/:article_id/comments. For retrieving all comments across articles, a custom route like /articles/-/comments can be used, but deep nesting should be avoided.

// Get comment list
v1.GET("/articles/:articles_id/comments", HandleGetComments)
// Add comment
v1.POST("/articles/:articles_id/comments", HandleAddComments)
// Update comment
v1.PUT("/articles/:articles_id/comments/:id", HandleUpdateComments)
// Delete comment
v1.DELETE("/articles/:articles_id/comments/:id", HandleDeleteComments)

5. Pagination, Sorting, Filtering

Typical query parameters include ?page=1&page_size=10 for pagination, ?sort=-create_at,+author for ordering, and field‑specific filters such as ?title=helloworld.

6. Unified Data Format

Adopt a consistent naming convention (snake_case, PascalCase, or camelCase) for request parameters; the author prefers snake_case. Define a generic response struct:

type Resp struct {
    Data  interface{} `json:"data"`
    Error string      `json:"error"`
}

Successful responses return Data, while errors populate Error.

7. Proper HTTP Status Codes

200 OK – successful requests

400 Bad Request – validation errors

401 Unauthorized – missing authentication

403 Forbidden – access denied

404 Not Found – unknown path

500 Internal Server Error – unexpected server error

These six codes cover most scenarios; 502 and 503 are rarely returned directly by application code.

8. API Versioning

Group routes under a version prefix such as /api/v1. When a new version is needed, add /api/v2 without breaking existing clients.

v1 := r.Group("/api/v1")
{
    v1.POST("/login", HandleLogin)
    v1.GET("/articles", HandleGetArticles)
    v1.GET("/articles/:id/comments", HandleGetComments)
    // ...
}

9. Leading Slash in Paths

All route definitions should start with a leading / for consistency, even if the framework adds it automatically.

10. Return Resources After Create/Update

POST and PUT handlers should respond with the newly created or updated resource representation.

11. Use HTTPS

Expose public APIs over HTTPS. This can be achieved by terminating TLS at a front‑end web server or enabling HTTPS directly in the backend service.

12. Standardized API Documentation

Generate API docs automatically from Go code comments using tools like Swag, which integrate seamlessly with Gin.

Conclusion

Good API design follows web standards, maintains consistency, and prioritizes clarity, security, and ease of use, ultimately delivering a better developer experience.