gorest

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.

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 projects, it is recommended to use version 1.6.x or higher.

Requirement

Go 1.19+

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

version: '3.9'
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

© Mahir Hasan 2019 - 2024

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