Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/laa-software-engineering/golang-rest-api-template
Template for REST API made with Golang using Gin framework, PostgreSQL database, JWT authentication, Redis cache and MongoDB for logging
https://github.com/laa-software-engineering/golang-rest-api-template
gin-framework gin-gonic go-example go-rest-api go-rest-api-docker go-restful golang
Last synced: 1 day ago
JSON representation
Template for REST API made with Golang using Gin framework, PostgreSQL database, JWT authentication, Redis cache and MongoDB for logging
- Host: GitHub
- URL: https://github.com/laa-software-engineering/golang-rest-api-template
- Owner: LAA-Software-Engineering
- License: mit
- Created: 2022-10-10T22:44:48.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-01-13T20:30:01.000Z (1 day ago)
- Last Synced: 2025-01-14T04:06:47.471Z (1 day ago)
- Topics: gin-framework, gin-gonic, go-example, go-rest-api, go-rest-api-docker, go-restful, golang
- Language: Go
- Homepage:
- Size: 51.7 MB
- Stars: 167
- Watchers: 5
- Forks: 35
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# golang-rest-api-template
[](https://raw.githubusercontent.com/araujo88/golang-rest-api-template/main/LICENSE)
[](https://github.com/araujo88/golang-rest-api-template/actions/workflows/go.yml)
## Overview
This repository provides a template for building a RESTful API using Go with features like JWT Authentication, rate limiting, Swagger documentation, and database operations using GORM. The application uses the Gin Gonic web framework and is containerized using Docker.
## Features
- RESTful API endpoints for CRUD operations.
- JWT Authentication.
- Rate Limiting.
- Swagger Documentation.
- PostgreSQL database integration using GORM.
- Redis cache.
- MongoDB for logging storage.
- Dockerized application for easy setup and deployment.
## Folder structure
```
golang-rest-api-template/
├── bin
│ └── server
├── cmd
│ └── server
│ └── main.go
├── docker-compose.yml
├── Dockerfile
├── docs
│ ├── docs.go
│ ├── swagger.json
│ └── swagger.yaml
├── go.mod
├── go.sum
├── LICENSE
├── Makefile
├── pkg
│ ├── api
│ │ ├── books.go
│ │ ├── books_test.go
│ │ ├── router.go
│ │ └── user.go
│ ├── auth
│ │ ├── auth.go
│ │ └── auth_test.go
│ ├── cache
│ │ ├── cache.go
│ │ ├── cache_mock.go
│ │ └── cache_test.go
│ ├── database
│ │ ├── db.go
│ │ ├── db_mock.go
│ │ └── db_test.go
│ ├── middleware
│ │ ├── api_key.go
│ │ ├── authenticateJWT.go
│ │ ├── cors.go
│ │ ├── rate_limit.go
│ │ ├── security.go
│ │ └── xss.go
│ └── models
│ ├── book.go
│ └── user.go
├── README.md
├── scripts
│ ├── generate_key
│ └── generate_key.go
└── vendor
```
## Getting Started
### Prerequisites
- Go 1.21+
- Docker
- Docker Compose
### Installation
1. Clone the repository
```bash
git clone https://github.com/araujo88/golang-rest-api-template
```
2. Navigate to the directory
```bash
cd golang-rest-api-template
```
3. Build and run the Docker containers
```bash
make setup && make build && make up
```
### Environment Variables
You can set the environment variables in the `.env` file. Here are some important variables:
- `POSTGRES_HOST`
- `POSTGRES_DB`
- `POSTGRES_USER`
- `POSTGRES_PASSWORD`
- `POSTGRES_PORT`
- `JWT_SECRET`
- `API_SECRET_KEY`
### API Documentation
The API is documented using Swagger and can be accessed at:
```
http://localhost:8001/swagger/index.html
```
## Usage
### Endpoints
- `GET /api/v1/books`: Get all books.
- `GET /api/v1/books/:id`: Get a single book by ID.
- `POST /api/v1/books`: Create a new book.
- `PUT /api/v1/books/:id`: Update a book.
- `DELETE /api/v1/books/:id`: Delete a book.
- `POST /api/v1/login`: Login.
- `POST /api/v1/register`: Register a new user.
### Authentication
To use authenticated routes, you must include the `Authorization` header with the JWT token.
```bash
curl -H "Authorization: Bearer " http://localhost:8001/api/v1/books
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
## End-to-End (E2E) Tests
This project contains end-to-end (E2E) tests to verify the functionality of the API. The tests are written in Python using the `pytest` framework.
### Prerequisites
Before running the tests, ensure you have the following:
- Python 3.x installed
- `pip` (Python package manager)
- The API service running locally or on a staging server
- API key available
### Setup
#### 1. Create a virtual environment (optional but recommended):
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
#### 2. Install dependencies:
```bash
pip install -r requirements.txt
```
The main dependency is `requests`, but you may need to include it in your `requirements.txt` file if it's not already listed.
#### 3. Set up the environment variables:
You need to set the `BASE_URL` and `API_KEY` as environment variables before running the tests.
For a **local** API service:
```bash
export BASE_URL=http://localhost:8001/api/v1
export API_KEY=your-api-key-here
```
For a **staging** server:
```bash
export BASE_URL=https://staging-server-url.com/api/v1
export API_KEY=your-api-key-here
```
On **Windows**, you can use:
```bash
set BASE_URL=http://localhost:8001/api/v1
set API_KEY=your-api-key-here
```
#### 4. Run the tests:
Once the environment variables are set, you can run the tests using `pytest`:
```bash
pytest test_e2e.py
```
### Test Structure
The tests will perform the following actions:
1. Register a new user and obtain a JWT token.
2. Create a new book in the system.
3. Retrieve all books and verify the created book is present.
4. Retrieve a specific book by its ID.
5. Update the book's details.
6. Delete the book and verify it is no longer accessible.
Each test includes assertions to ensure that the API behaves as expected.