gorest

package module
v1.6.15 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2023 License: MIT Imports: 0 Imported by: 0

README

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: v1.4.5

Requirement

Go 1.19+

Supported databases

  • MySQL
  • PostgreSQL
  • SQLite3
  • Redis
  • MongoDB

Note: gorest uses GORM as its ORM

Features

  • built on top of Gin
  • 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 with Argon2id
  • 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)
  • 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 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

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

  • 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 should be left unchanged.
  • DBNAME must contain the full path and the database file name; i.e,
/user/location/database.db

Contributing

Please see CONTRIBUTING to join this amazing project.

Code of conduct

Please see this document.

License

© Mahir Hasan 2019 - 2023

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 application
 main function of the 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
 Package migrate to migrate the schema
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 ...
 Package handler ...
router
Package router contains all routes
 Package router contains all routes
Package handler ...
 Package handler ...
lib
Package lib provides additional functionalities to the application: - AES encryption-decryption - Argon2id hashing - SHA hashing - Two-factor authentication - Email format validation along with MX lookup
 Package lib provides additional functionalities to the application: - AES encryption-decryption - Argon2id hashing - SHA hashing - Two-factor authentication - Email format validation along with MX lookup
middleware
Package middleware contains: - CORS - Application firewall - Pongo2 template engine - JWT - Sentry logger - Two-factor auth validator
 Package middleware contains: - CORS - Application firewall - Pongo2 template engine - JWT - Sentry logger - Two-factor auth validator
renderer
Package renderer uses template engine to render and serve HTML pages
 Package renderer uses template engine to render and serve HTML pages
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.