rest - Streamlined Go RESTful APIs using Clean Architecture and Contemporary Tools

Overview of REST with Clean Architecture in Go

REST with Clean Architecture for Go is a module designed to implement the HTTP transport level for building robust REST services using the github.com/swaggest/usecase package. This project emphasizes maintaining a single source of truth for documentation, validation, and input/output handling of HTTP APIs, making it easier for developers to build clean and efficient REST services.

Goals

The primary goals of the project are:

Unified Documentation: It strives to keep the documentation, validation, and input/output handling in sync, ensuring consistency across these areas.
Simplicity and Efficiency: By avoiding reliance on compile-time code generation and abstracting HTTP details, the project aims to improve productivity and reliability.
Flexibility: While simplifying common cases, it still allows for low-level customizations for more complex scenarios.
Performance: The project focuses on maintaining good performance with minimal garbage collection impact.

Non-Goals

The project explicitly avoids supporting outdated documentation schemas like Swagger 2.0 or RAML, zero allocations, and explicit support for XML in request or response bodies.

Key Features

Compatibility: Works seamlessly with net/http.
Routing: Utilizes the flexible and modular github.com/go-chi/chi router.
Clean Architecture: Business logic is decoupled using Clean Architecture principles.
OpenAPI Support: Generates type-safe OpenAPI 3.0/3.1 documentation automatically.
Validation: Provides automatic JSON schema validation for incoming requests and outgoing responses.
Compression: Supports dynamic gzip compression for efficient data transfer.
Modular Design: Offers a generic interface for use case interactors.
Swagger Integration: Comes with an embedded Swagger UI for easy API exploration.

Usage

Developers can refer to a comprehensive tutorial demonstrating how to create RESTful APIs with Go, incorporating JSON schema validation and OpenAPI documentation.

Request and Response Handling

Request Decoder: The request decoder maps HTTP request fields to a Go struct, which acts as the input port for a use case. This structure is defined by using field tags that specify where data should be pulled from (path, query, header, etc.).
```
type helloInput struct {
    Locale string `query:"locale"`
    Name   string `path:"name"`
}
```
Response Encoder: Similarly, the response encoder takes fields from a Go struct and writes them to the HTTP response.
```
type helloOutput struct {
    Message string `json:"message"`
}
```

Setting Up Use Cases

Use cases are defined through interactors, which are functions that describe input and output ports. These interactors handle the core business logic, interacting with incoming requests and outgoing responses.

u := usecase.NewInteractor(func(ctx context.Context, input helloInput, output *helloOutput) error {
    output.Message = fmt.Sprintf("Hello, %s!", input.Name)
    return nil
})

Web Service Initialization

The web.Service API facilitates easy configuration and management of middleware and use cases for a web server. It also integrates with OpenAPI to enrich API documentation.

service := web.NewService(openapi31.NewReflector())
service.Post("/albums", postAlbums(), nethttp.SuccessStatus(http.StatusCreated))

Security

The module includes basic authentication features, allowing secure access control over REST endpoints with mechanisms like HTTP Basic Auth and session cookies.

Performance Optimization

For enhanced performance, developers can manually implement request loading to bypass automatic decoding and validation steps, or leverage alternative libraries like fasthttp.

Conclusion

REST with Clean Architecture for Go presents a robust solution for building scalable and maintainable REST APIs. By focusing on structuring code with Clean Architecture principles, it ensures separation of concerns and enhances code readability and maintainability, while providing automatic documentation and validation features.