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.

Versioning

1.x.y

1: production-ready

x: breaking changes

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

Important

Version 1.6.x contains breaking changes!

Note: For version 1.4.5 (obsolete): v1.4.5

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

Requirement

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)

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
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

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

# syntax=docker/dockerfile:1
name: go
services:
  goapi:
    image: golang:latest
    container_name: goapi
    working_dir: /app/
    restart: unless-stopped:10s
    command: /app/goapi
    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:

For version 1.6.x, please check the project in example

For version 1.4.x and 1.5.x, Wiki (obsolete)

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
check the Wiki and example for tutorials and implementations

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`
database	dbConnect.go	`150 - 155`, `161`
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 ./...

Contributing

Please see CONTRIBUTING to join this amazing project.

Code of conduct

Please see this document.

License

Released under the MIT license