Redirected from github.com/piLinux/GoREST.

gorest

package module

v1.11.1 Latest Latest Go to latest Published: Feb 20, 2026 License: MIT Imports: 0 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/pilinux/gorest

Links

Open Source Insights

README ¶

gorest | RESTful API Starter kit

gorest is a starter kit, written in Golang with Gin framework, for rapid prototyping and developing a RESTful API. The source code is released under the MIT license and is free for any personal or commercial project.

Reasons to use gorest

always up-to-date with direct and indirect dependencies
every change is manually reviewed and tested before release
thoroughly scanned for security vulnerabilities and supply chain attacks
connect to a database and start building your RESTful API within minutes

LLM interface

This repository provides a complete, machine-readable interface for LLMs and MCP servers via llms.txt.

Direct link:

llms.txt

The file contains authoritative context about this repository, including purpose, capabilities, usage guidance, and constraints. MCP-compatible servers and autonomous agents should consume this file as the primary integration entry point.

Additional agent-specific behavior is documented in AGENTS.md.

OpenCode skills

If you use the OpenCode agent (or a compatible agent runner), no extra setup is required:

The agent should read llms.txt for authoritative project context.
The agent should follow AGENTS.md for repo-specific workflows (build, lint, test env).
Task-specific skill guides live in .agents/skills/ and are intended to be automatically selected by the agent during runs.

You can also request a skill explicitly in your prompt when you want a specific workflow. Examples:

"Use test-runner and run go test -v -cover ./... with setTestEnv.sh"
"Use ci-orchestrator and reproduce CI locally"
"Use config-loader-helper and list required env vars for JWT + Redis"
"Use migration-helper and assess the schema impact of a model change"

If you contribute to gorest (or build your own project based on it) and you add a new recurring workflow, document it as a skill in .agents/skills/<skill-name>/SKILL.md so agents can discover and apply it consistently.

Requirement

Go 1.24.1+ (for versions 1.11.x)
Go 1.24.1+ (for versions 1.10.x)
Go 1.23+ (for versions 1.9.x)
Go 1.23+ (for versions 1.8.x)
Go 1.21+ (for versions 1.7.x)
Go 1.20+ (for versions 1.6.x)

For all new projects, it is recommended to use version 1.11.x or higher.

Migration guides for breaking changes

From 1.10.x to 1.11.x:
- If you are using 2FA feature from gorest, see release notes for version 1.10.5.
- If you are using MongoDB, see example code for the new MongoDB implementation.

Important

Go1.24.0 is not supported due to the issue. Please use any supported Go version excluding 1.24.0.

Versioning

1.x.y

1: production-ready

x: breaking changes

y: new functionality or bug fixes in a backwards compatible manner

Supported databases

MySQL
PostgreSQL
SQLite3
Redis
MongoDB

Note: gorest uses GORM as its ORM

Features

built on top of Gin
option to enable encryption at rest for user private information
use the supported databases without writing any extra configuration files
environment variables using GoDotEnv
CORS policy
basic auth
two-factor authentication
JWT using golang-jwt/jwt
password hashing using Argon2id with optional secret (NIST 800-63B recommends using a secret value of at least 112 bits)
JSON protection from hijacking
simple firewall (whitelist/blacklist IP)
email validation (pattern + MX lookup)
email verification (sending verification code)
forgotten password recovery
render HTML templates
forward error logs and crash reports to sentry.io
handle authentication tokens on client devices' cookies
logout (individually enable option - delete tokens from cookies, ban active tokens)
rate limiting (IP-based)
option to validate origin of the request
super easy to learn and use - lots of example codes

Supported JWT signing algorithms

HS256: HMAC-SHA256
HS384: HMAC-SHA384
HS512: HMAC-SHA512
ES256: ECDSA Signature with SHA-256
ES384: ECDSA Signature with SHA-384
ES512: ECDSA Signature with SHA-512
EdDSA: Ed25519 variant (EdDSA over the Edwards25519 curve) is supported
RS256: RSA Signature with SHA-256
RS384: RSA Signature with SHA-384
RS512: RSA Signature with SHA-512

Procedures to generate HS256, HS384, HS512 keys using openssl:

HS256: openssl rand -base64 32
HS384: openssl rand -base64 48
HS512: openssl rand -base64 64

Procedures to generate public-private key pair using openssl:

ECDSA

ES256

prime256v1: X9.62/SECG curve over a 256 bit prime field, also known as P-256 or NIST P-256
widely used, recommended for general-purpose cryptographic operations

openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

ES384

secp384r1: NIST/SECG curve over a 384 bit prime field

openssl ecparam -name secp384r1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

ES512

secp521r1: NIST/SECG curve over a 521 bit prime field

openssl ecparam -name secp521r1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem

EdDSA

Ed25519

openssl genpkey -algorithm Ed25519 -out private-key.pem
openssl pkey -in private-key.pem -pubout -out public-key.pem

RSA

RS256

openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in private-key.pem -pubout -out public-key.pem

RS384

openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:3072
openssl rsa -in private-key.pem -pubout -out public-key.pem

RS512

openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -in private-key.pem -pubout -out public-key.pem

Example docker compose file

name: dev
services:
  goapi:
    image: golang:latest
    container_name: goapi
    working_dir: /app
    restart: unless-stopped
    command: /app/goapi
    environment:
      - TZ=Europe/Berlin
    ports:
      - "127.0.0.1:8000:8999"
    volumes:
      - ./app:/app

Start building

Please study the .env.sample file. It is one of the most crucial files required to properly set up a new project. Please rename the .env.sample file to .env, and set the environment variables according to your own instance setup.

Tutorials:

Please check example projects:

recommended - example2 [interface-driven design, with a focus on modularity and testability]
example [simplicity and ease of use, with a focus on rapid development and prototyping]

convention over configuration

import (
  "github.com/gin-gonic/gin"

  gconfig "github.com/pilinux/gorest/config"
  gcontroller "github.com/pilinux/gorest/controller"
  gdatabase "github.com/pilinux/gorest/database"
  gmiddleware "github.com/pilinux/gorest/lib/middleware"
)

install a relational (SQLite3, MySQL or PostgreSQL), Redis, or Mongo database
for 2FA, a relational + a redis database is required
set up an environment to compile the Go codes (a quick tutorial for any Debian based OS)
install git

Note: For MySQL driver, please check issue: 7

Note For SQLite3:

DBUSER, DBPASS, DBHOST and DBPORT environment variables are not required.
DBNAME must contain the full or relative path of the database file name; i.e,

/user/location/database.db

or,

./database.db

Debugging with Error Codes

package	file	error code range
controller	login.go	`1011 - 1012`
controller	twoFA.go	`1041 - 1044`
handler	auth.go	`1001 - 1003`
handler	login.go	`1013 - 1014`
handler	logout.go	`1016`
handler	passwordReset.go	`1021 - 1030`
handler	twoFA.go	`1051 - 1056`
handler	verification.go	`1061 - 1065`
service	common.go	`401 - 406`
service	security.go	`501`

Development

For testing:

export TEST_ENV_URL="https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux/.env"
export TEST_INDEX_HTML_URL="https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux/index.html"
export TEST_KEY_FILE_LOCATION="https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux"
export TEST_SENTRY_DSN="please_set_your_sentry_DSN_here"

go test -v -cover ./...

For cross-compilation:

GOOS=linux GOARCH=arm64 go build
GOOS=linux GOARCH=amd64 go build

GOOS=darwin GOARCH=arm64 go build
GOOS=darwin GOARCH=amd64 go build

GOOS=windows GOARCH=arm64 go build
GOOS=windows GOARCH=amd64 go build

Contributing

Please see CONTRIBUTING to join this amazing project.

Code of conduct

Please see this document.

License

Released under the MIT license

Documentation ¶

Overview ¶

Package gorest is a Go RESTful API starter kit with Gin, JWT, GORM (MySQL, PostgreSQL, SQLite), Redis, Mongo, 2FA, email verification, and password recovery.

Source Files ¶

View all Source files

doc.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
config Package config reads all environment variables and sets up the base configuration for a functional application.	Package config reads all environment variables and sets up the base configuration for a functional application.
controller Package controller contains all the controllers of the application.	Package controller contains all the controllers of the application.
database Package database handles connections to different types of databases.	Package database handles connections to different types of databases.
migrate Package migrate handles database schema migrations.	Package migrate handles database schema migrations.
model Package model contains all the models required for a functional database management system.	Package model contains all the models required for a functional database management system.
example Package main is the entry point of the example application.	Package main is the entry point of the example application.
controller Package controller contains all the controllers of the application.	Package controller contains all the controllers of the application.
database/migrate Package migrate handles schema migration for the example application.	Package migrate handles schema migration for the example application.
database/model Package model contains all the models required for a functional database management system.	Package model contains all the models required for a functional database management system.
handler Package handler contains the business logic of the example application.	Package handler contains the business logic of the example application.
router Package router contains all routes of the example application.	Package router contains all routes of the example application.
example2
cmd/app command Package main is the entry point of the example2 application.	Package main is the entry point of the example2 application.
internal/database/migrate Package migrate handles database schema migration for the example2 application.	Package migrate handles database schema migration for the example2 application.
internal/database/model Package model contains all the models required for a functional database management system.	Package model contains all the models required for a functional database management system.
internal/handler Package handler provides HTTP handler implementations for the application's API endpoints.	Package handler provides HTTP handler implementations for the application's API endpoints.
internal/repo Package repo provides data access and persistence logic for the application's models.	Package repo provides data access and persistence logic for the application's models.
internal/router Package router contains all routes of the example2 application.	Package router contains all routes of the example2 application.
internal/service Package service provides business logic and application services for the API.	Package service provides business logic and application services for the API.
handler Package handler contains business logic invoked by controllers.	Package handler contains business logic invoked by controllers.
lib Package lib provides additional functionalities to the application:	Package lib provides additional functionalities to the application:
middleware Package middleware contains:	Package middleware contains:
renderer Package renderer uses a template engine to render and serve HTML pages.	Package renderer uses a template engine to render and serve HTML pages.
server Package server provides utilities for managing HTTP server lifecycle operations.	Package server provides utilities for managing HTTP server lifecycle operations.
service Package service contains common functions used by the whole application.	Package service contains common functions used by the whole application.