Skip to content
/ gorest Public

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

License

Notifications You must be signed in to change notification settings

pilinux/gorest

Repository files navigation

gorest | RESTful API Starter kit

CodeQL Go Linter Codecov Go Reference Go Report Card CodeFactor codebeat badge 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.

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.20+

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