A Go REST API boilerplate emphasizing clean architecture, thorough testing, and flexible deployment options (Docker, Kubernetes, Serverless). Includes a full suite of tests and clear project structure for maintainability and scalability.
MIT License
This Minimalistic Go REST API boilerplate establishes a strong foundation for your API development, emphasizing clean architecture, thorough testing, and flexible deployment options. The modular structure ensures maintainability and scalability by promoting a clear separation of concerns, making it easy to modify and extend your API as needed witouth a steep learning curve on how the API is setup or dependencies.
Comprehensive testing is essential for a reliable and secure API. The boilerplate includes a full suite of tests, including unit tests, API security tests, service contract tests, and performance benchmarks. With these tests in place, you can confidently deploy your API using the method that best suits your needs. You can find guides on deploying on different platforms in the Deployments section.
Clone this repository.
Navigate to the project root.
Run go mod tidy
to ensure all dependencies are correctly installed.
Copy the .env.example
file to .env
:
cp .env.example .env
Open the .env
file and set the TOKEN_URL
environment variable to the GitHub API URL:
TOKEN_URL=https://api.github.com/user
5.1 If you want to use other providers, you can do so by setting the TOKEN_URL
environment variable to the provider's API URL and change token.go
file to use the correct provider.
Use the provided Makefile commands for common tasks:
make build
: Build the applicationmake test
: Run all testsmake run
: Run the application locallyTo run the documentation locally:
make docs
http://localhost:3001
in your browserThis will start a Docusaurus site with comprehensive project documentation.
For the most up-to-date and comprehensive documentation, please visit our official documentation site. This site includes:
go-rest-api/
├── cmd/
│ └── api/
│ └── main.go
├── internal/
│ ├── api/
│ │ ├── handlers/
│ │ ├── middleware/
│ │ └── routes.go
│ ├── config/
│ ├── models/
│ ├── repository/
│ └── service/
├── pkg/
├── scripts/
├── tests/
│ ├── integration/
│ └── unit/
├── deployments/
│ ├── docker/
│ ├── kubernetes/
│ └── serverless/
├── docs/
├── .gitignore
├── go.mod
├── go.sum
├── Makefile
├── LICENSE
└── README.md
cmd/
Contains the main applications for this project. The api/
subdirectory is where the main.go file for starting the API server resides.
api/main.go
: Entry point of the application. Initializes and starts the API server.internal/
Houses packages that are specific to this project and not intended for external use.
api/
: Contains API-specific code.
handlers/
: Request handlers for each API endpoint.middleware/
: Custom middleware functions.routes.go
: Defines API routes and links them to handlers.config/
: Configuration management for the application.models/
: Data models and DTOs (Data Transfer Objects).repository/
: Data access layer, interfacing with the database.service/
: Business logic layer, implementing core functionality.pkg/
Shared packages that could potentially be used by external projects. Place reusable, non-project-specific code here.
scripts/
Utility scripts for development, CI/CD, database migrations, etc.
tests/
Contains test files separated into integration and unit tests.
integration/
: API-level and end-to-end tests.unit/
: Unit tests for individual functions and methods.deployments/
Configuration files and scripts for deploying the application.
docker/
: Dockerfile and related configurations for containerization.kubernetes/
: Kubernetes manifests for orchestration.serverless/
: Serverless configuration files for cloud function deployment.docs/
Project documentation, API specifications, and any other relevant documentation.
.gitignore
: Specifies intentionally untracked files to ignore.go.mod
and go.sum
: Go module files for dependency management.Makefile
: Defines commands for building, testing, and deploying the application.LICENSE
: Contains the MIT License text.README.md
: This file, providing an overview of the project structure.internal/
.tests/integration/
directory.docs/
directory as necessary.scripts/
directory for any automation tasks.deployments/
if there are infrastructure changes.This project supports multiple deployment options.
Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
This project is licensed under the MIT License - see the LICENSE file for details.