{"id":13630272,"url":"https://github.com/pilinux/gorest","last_synced_at":"2025-05-15T18:03:38.058Z","repository":{"id":37335372,"uuid":"175689430","full_name":"pilinux/gorest","owner":"pilinux","description":"Go RESTful API starter kit with Gin, JWT, GORM (MySQL, PostgreSQL, SQLite), Redis, Mongo, 2FA, email verification, password recovery","archived":false,"fork":false,"pushed_at":"2025-05-15T16:50:09.000Z","size":1091,"stargazers_count":444,"open_issues_count":2,"forks_count":55,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-15T18:03:18.956Z","etag":null,"topics":["api","go","golang","golang-api","golang-rest","gorest","gorestapi","jwt","jwt-authentication","mit-license","mongodb","mysql","open-source","opensource","postgresql","redis","rest-api","restful","restful-api","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pilinux.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-03-14T19:50:31.000Z","updated_at":"2025-05-15T08:05:25.000Z","dependencies_parsed_at":"2023-10-12T02:17:50.720Z","dependency_job_id":"bedad41e-bf20-46db-a429-1c2909417bba","html_url":"https://github.com/pilinux/gorest","commit_stats":{"total_commits":533,"total_committers":5,"mean_commits":106.6,"dds":"0.20262664165103195","last_synced_commit":"43cb645bd5436576acb712f9da4c95ab7256d982"},"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilinux%2Fgorest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilinux%2Fgorest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilinux%2Fgorest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pilinux%2Fgorest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pilinux","download_url":"https://codeload.github.com/pilinux/gorest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254394719,"owners_count":22063984,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","go","golang","golang-api","golang-rest","gorest","gorestapi","jwt","jwt-authentication","mit-license","mongodb","mysql","open-source","opensource","postgresql","redis","rest-api","restful","restful-api","sqlite3"],"created_at":"2024-08-01T22:01:36.761Z","updated_at":"2025-05-15T18:03:38.052Z","avatar_url":"https://github.com/pilinux.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# gorest | RESTful API Starter kit\n\n\u003cimg align=\"right\" width=\"350px\" src=\"https://cdn.pilinux.workers.dev/images/GoREST/logo/GoREST-Logo.png\"\u003e\n\n![CodeQL][02]\n![Go][07]\n![Linter][08]\n[![Codecov][04]][05]\n[![Go Reference][14]][15]\n[![Go Report Card](https://goreportcard.com/badge/github.com/pilinux/gorest)][01]\n[![CodeFactor](https://www.codefactor.io/repository/github/pilinux/gorest/badge)][06]\n[![codebeat badge](https://codebeat.co/badges/12c01a53-4745-4f90-ad2b-a95c94e4b432)][03]\n[![MIT license](https://img.shields.io/badge/license-MIT-brightgreen.svg)][13]\n[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)][62]\n\ngorest is a starter kit, written in [Golang][11] with [Gin framework][12],\nfor rapid prototyping and developing a RESTful API. The source code is released\nunder the [MIT license][13] and is free for any personal or commercial project.\n\n## Versioning\n\n`1.x.y`\n\n`1`: production-ready\n\n`x`: breaking changes\n\n`y`: new functionality or bug fixes in a backwards compatible manner\n\n## Important\n\nVersion `1.6.x` contains breaking changes!\n\n_Note:_ For version `1.4.5` (obsolete): [v1.4.5](https://github.com/pilinux/gorest/tree/v1.4.5)\n\nFor all new projects, it is recommended to use version `1.9.x` or higher.\n\n## Requirement\n\n- `Go 1.23+` (for versions `1.9.x`)\n- `Go 1.23+` (for versions `1.8.x`)\n- `Go 1.21+` (for versions `1.7.x`)\n- `Go 1.20+` (for versions `1.6.x`)\n\n## Supported databases\n\n- [x] MySQL\n- [x] PostgreSQL\n- [x] SQLite3\n- [x] Redis\n- [x] MongoDB\n\n_Note:_ gorest uses [GORM][21] as its ORM\n\n## Features\n\n- [x] built on top of [Gin][12]\n- [x] option to enable encryption at rest for user private information\n- [x] use the supported databases without writing any extra configuration files\n- [x] environment variables using [GoDotEnv][51]\n- [x] CORS policy\n- [x] basic auth\n- [x] two-factor authentication\n- [x] JWT using [golang-jwt/jwt][16]\n- [x] password hashing using `Argon2id` with optional secret (NIST 800-63B\n      recommends using a secret value of at least 112 bits)\n- [x] JSON protection from hijacking\n- [x] simple firewall (whitelist/blacklist IP)\n- [x] email validation (pattern + MX lookup)\n- [x] email verification (sending verification code)\n- [x] forgotten password recovery\n- [x] render `HTML` templates\n- [x] forward error logs and crash reports to [sentry.io][17]\n- [x] handle authentication tokens on client devices' cookies\n- [x] logout (individually enable option - delete tokens from cookies, ban active tokens)\n- [x] rate limiting (IP-based)\n- [x] option to validate origin of the request\n- [x] super easy to learn and use - lots of example codes\n\n## Supported JWT signing algorithms\n\n- [x] HS256: HMAC-SHA256\n- [x] HS384: HMAC-SHA384\n- [x] HS512: HMAC-SHA512\n- [x] ES256: ECDSA Signature with SHA-256\n- [x] ES384: ECDSA Signature with SHA-384\n- [x] ES512: ECDSA Signature with SHA-512\n- [x] RS256: RSA Signature with SHA-256\n- [x] RS384: RSA Signature with SHA-384\n- [x] RS512: RSA Signature with SHA-512\n\nProcedures to generate HS256, HS384, HS512 keys using openssl:\n\n- HS256: `openssl rand -base64 32`\n- HS384: `openssl rand -base64 48`\n- HS512: `openssl rand -base64 64`\n\nProcedures to generate public-private key pair using openssl:\n\n### ECDSA\n\n#### ES256\n\n- prime256v1: X9.62/SECG curve over a 256 bit prime field, also known as P-256 or NIST P-256\n- widely used, recommended for general-purpose cryptographic operations\n\n```bash\nopenssl ecparam -name prime256v1 -genkey -noout -out private-key.pem\nopenssl ec -in private-key.pem -pubout -out public-key.pem\n```\n\n#### ES384\n\n- secp384r1: NIST/SECG curve over a 384 bit prime field\n\n```bash\nopenssl ecparam -name secp384r1 -genkey -noout -out private-key.pem\nopenssl ec -in private-key.pem -pubout -out public-key.pem\n```\n\n#### ES512\n\n- secp521r1: NIST/SECG curve over a 521 bit prime field\n\n```bash\nopenssl ecparam -name secp521r1 -genkey -noout -out private-key.pem\nopenssl ec -in private-key.pem -pubout -out public-key.pem\n```\n\n### RSA\n\n#### RS256\n\n```bash\nopenssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:2048\nopenssl rsa -in private-key.pem -pubout -out public-key.pem\n```\n\n#### RS384\n\n```bash\nopenssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:3072\nopenssl rsa -in private-key.pem -pubout -out public-key.pem\n```\n\n#### RS512\n\n```bash\nopenssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:4096\nopenssl rsa -in private-key.pem -pubout -out public-key.pem\n```\n\n## Example docker compose file\n\n```yml\nname: dev\nservices:\n  goapi:\n    image: golang:latest\n    container_name: goapi\n    working_dir: /app\n    restart: unless-stopped\n    command: /app/goapi\n    environment:\n      - TZ=Europe/Berlin\n    ports:\n      - \"127.0.0.1:8000:8999\"\n    volumes:\n      - ./app:/app\n```\n\n## Start building\n\nPlease study the `.env.sample` file. It is one of the most crucial files required\nto properly set up a new project. Please rename the `.env.sample` file to `.env`,\nand set the environment variables according to your own instance setup.\n\n_Tutorials:_\n\nFor version `1.6.x` and above, please check the project in [example](example)\n\nFor version `1.4.x` and `1.5.x`, [Wiki][10] (obsolete)\n\n- convention over configuration\n\n```go\nimport (\n  \"github.com/gin-gonic/gin\"\n\n  gconfig \"github.com/pilinux/gorest/config\"\n  gcontroller \"github.com/pilinux/gorest/controller\"\n  gdatabase \"github.com/pilinux/gorest/database\"\n  gmiddleware \"github.com/pilinux/gorest/lib/middleware\"\n)\n```\n\n- install a relational (SQLite3, MySQL or PostgreSQL), Redis, or Mongo database\n- for 2FA, a relational + a redis database is required\n- set up an environment to compile the Go codes (a [quick tutorial][41]\n  for any Debian based OS)\n- install `git`\n\n_Note:_ For **MySQL** driver, please [check issue: 7][42]\n\n**Note For SQLite3:**\n\n- `DBUSER`, `DBPASS`, `DBHOST` and `DBPORT` environment variables are not required.\n- `DBNAME` must contain the full or relative path of the database file name; i.e,\n\n```env\n/user/location/database.db\n```\n\nor,\n\n```env\n./database.db\n```\n\n## Debugging with Error Codes\n\n| package    | file             | error code range   |\n| ---------- | ---------------- | ------------------ |\n| controller | login.go         | `1011 - 1012`      |\n| controller | twoFA.go         | `1041 - 1044`      |\n| database   | dbConnect.go     | `150 - 155`, `161` |\n| handler    | auth.go          | `1001 - 1003`      |\n| handler    | login.go         | `1013 - 1014`      |\n| handler    | logout.go        | `1016`             |\n| handler    | passwordReset.go | `1021 - 1030`      |\n| handler    | twoFA.go         | `1051 - 1056`      |\n| handler    | verification.go  | `1061 - 1065`      |\n| service    | common.go        | `401 - 406`        |\n| service    | security.go      | `501`              |\n\n## Development\n\nFor testing:\n\n```bash\nexport TEST_ENV_URL=\"https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux/.env\"\nexport TEST_INDEX_HTML_URL=\"https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux/index.html\"\nexport TEST_KEY_FILE_LOCATION=\"https://s3.nl-ams.scw.cloud/ci.config/github.action/gorest.pilinux\"\nexport TEST_SENTRY_DSN=\"please_set_your_sentry_DSN_here\"\n\ngo test -v -cover ./...\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING][61] to join this amazing project.\n\n## Code of conduct\n\nPlease see [this][62] document.\n\n## License\n\n© Mahir Hasan 2019 - 2025\n\nReleased under the [MIT license][13]\n\n[01]: https://goreportcard.com/report/github.com/pilinux/gorest\n[02]: https://github.com/pilinux/gorest/actions/workflows/codeql-analysis.yml/badge.svg\n[03]: https://codebeat.co/projects/github-com-pilinux-gorest-main\n[04]: https://codecov.io/gh/pilinux/gorest/branch/main/graph/badge.svg?token=xGLBRrCAvB\n[05]: https://codecov.io/gh/pilinux/gorest\n[06]: https://www.codefactor.io/repository/github/pilinux/gorest\n[07]: https://github.com/pilinux/gorest/actions/workflows/go.yml/badge.svg\n[08]: https://github.com/pilinux/gorest/actions/workflows/golangci-lint.yml/badge.svg\n[10]: https://github.com/pilinux/gorest/wiki\n[11]: https://github.com/golang/go\n[12]: https://github.com/gin-gonic/gin\n[13]: LICENSE\n[14]: https://pkg.go.dev/badge/github.com/pilinux/gorest\n[15]: https://pkg.go.dev/github.com/pilinux/gorest\n[16]: https://github.com/golang-jwt/jwt\n[17]: https://sentry.io/\n[21]: https://gorm.io\n[41]: https://github.com/pilinux/HowtoCode/blob/master/Golang/1.Intro/Installation.md\n[42]: https://github.com/pilinux/gorest/issues/7\n[51]: https://github.com/joho/godotenv\n[61]: CONTRIBUTING.md\n[62]: CODE_OF_CONDUCT.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpilinux%2Fgorest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpilinux%2Fgorest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpilinux%2Fgorest/lists"}