gorest

package module
v1.10.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 22, 2025 License: MIT Imports: 0 Imported by: 0

README

gorest | RESTful API Starter kit

CodeQL Go Linter Codecov Go Reference Ask DeepWiki Go Report Card CodeFactor MIT license Contributor Covenant

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

Requirement

  • 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.10.x or higher.

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

© Mahir Hasan 2019 - 2025

Released under the MIT license

Documentation

Overview

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

Source Files

View all Source files

Directories

Path Synopsis
Package config is responsible for reading all environment variables and set up the base configuration for a functional application
 Package config is responsible for reading all environment variables and set up the base configuration for a functional application
Package controller contains all the controllers of the application
 Package controller contains all the controllers of the application
Package database handles connections to different types of databases
 Package database handles connections to different types of databases
migrate
Package migrate to migrate the schema
 Package migrate to migrate the schema
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
main function of the example application
 main function 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 to migrate the schema for the example application
 Package migrate to migrate the schema 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 of the example application
 Package handler 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
main function of the example2 application.
 main function of the example2 application.
internal/database/migrate
Package migrate to migrate database schema for the example2 application.
 Package migrate to migrate database schema 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.
Package handler sits in between controller and database services.
 Package handler sits in between controller and database services.
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 template engine to render and serve HTML pages
 Package renderer uses 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.
Package service contains common functions used by the whole application
 Package service contains common functions used by the whole application

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.