SkillAgentSearch skills...

Gorest

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

GenerateConvertImprove

Install / Use

/learn @pilinux/Gorest
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

gorest | RESTful API Starter kit

<!-- markdownlint-disable MD033 --> <img align="right" alt="GoREST logo" width="350px" src="https://cdn.pilinux.workers.dev/images/GoREST/logo/GoREST-Logo.png"> <!-- markdownlint-enable MD033 -->

![CodeQL][02] ![Go][07] ![Linter][08] [![Codecov][04]][05] [![Go Reference][14]][15] [![Ask DeepWiki][18]][19] [CodeFactor][06] [MIT license][13] [Contributor Covenant][62]

gorest is a starter kit, written in [Golang][11] with [Gin framework][12], for rapid prototyping and developing a RESTful API. The source code is released under the [MIT license][13] 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

LLM interface

This repository provides a complete, machine-readable interface for LLMs and MCP servers via llms.txt.

Direct link:

The file contains authoritative context about this repository, including purpose, capabilities, usage guidance, and constraints. MCP-compatible servers and autonomous agents should consume this file as the primary integration entry point.

Additional agent-specific behavior is documented in [AGENTS.md][20].

OpenCode skills

If you use the OpenCode agent (or a compatible agent runner), no extra setup is required:

  • The agent should read llms.txt for authoritative project context.
  • The agent should follow AGENTS.md for repo-specific workflows (build, lint, test env).
  • Task-specific skill guides live in .agents/skills/ and are intended to be automatically selected by the agent during runs.

You can also request a skill explicitly in your prompt when you want a specific workflow. Examples:

  • "Use test-runner and run go test -v -cover ./... with setTestEnv.sh"
  • "Use ci-orchestrator and reproduce CI locally"
  • "Use config-loader-helper and list required env vars for JWT + Redis"
  • "Use migration-helper and assess the schema impact of a model change"

If you contribute to gorest (or build your own project based on it) and you add a new recurring workflow, document it as a skill in .agents/skills/<skill-name>/SKILL.md so agents can discover and apply it consistently.

Requirement

  • Go 1.25.0+ (for versions 1.12.x)
  • Go 1.24.1+ (for versions 1.11.x)
  • 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.12.x or higher.

Migration guides for breaking changes

  • From 1.10.x to 1.11.x:
    • If you are using 2FA feature from gorest, see release notes for version 1.10.5.
    • If you are using MongoDB, see example code for the new MongoDB implementation.

Important

  • Go1.24.0 is not supported due to the [issue][22]. 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

  • [x] MySQL
  • [x] PostgreSQL
  • [x] SQLite3
  • [x] Redis
  • [x] MongoDB

Note: gorest uses [GORM][21] as its ORM

Features

  • [x] built on top of [Gin][12]
  • [x] option to enable encryption at rest for user private information
  • [x] use the supported databases without writing any extra configuration files
  • [x] environment variables using [GoDotEnv][51]
  • [x] CORS policy
  • [x] basic auth
  • [x] two-factor authentication
  • [x] JWT using [golang-jwt/jwt][16]
  • [x] password hashing using Argon2id with optional secret (NIST 800-63B recommends using a secret value of at least 112 bits)
  • [x] JSON protection from hijacking
  • [x] simple firewall (whitelist/blacklist IP)
  • [x] email validation (pattern + MX lookup)
  • [x] email verification (sending verification code)
  • [x] forgotten password recovery
  • [x] render HTML templates
  • [x] forward error logs and crash reports to [sentry.io][17]
  • [x] handle authentication tokens on client devices' cookies
  • [x] logout (individually enable option - delete tokens from cookies, ban active tokens)
  • [x] rate limiting (IP-based)
  • [x] option to validate origin of the request
  • [x] super easy to learn and use - lots of example codes

Supported JWT signing algorithms

  • [x] HS256: HMAC-SHA256
  • [x] HS384: HMAC-SHA384
  • [x] HS512: HMAC-SHA512
  • [x] ES256: ECDSA Signature with SHA-256
  • [x] ES384: ECDSA Signature with SHA-384
  • [x] ES512: ECDSA Signature with SHA-512
  • [x] EdDSA: Ed25519 variant (EdDSA over the Edwards25519 curve) is supported
  • [x] RS256: RSA Signature with SHA-256
  • [x] RS384: RSA Signature with SHA-384
  • [x] 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][41] for any Debian based OS)
  • install git

Note: For MySQL driver, please [check issue: 7][42]

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

pilinux

View profile

View on GitHub
GitHub Stars489
CategoryData
Updated15h ago
Forks62
pilinux/gorest

Languages

Go

Security Score

100/100

Audited on Mar 27, 2026

No findings