Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dzungtran/echo-rest-api
A Golang restful API boilerplate based on Echo framework v4. Includes tools for module generation, db migration, authorization, modular, authentication and more.
https://github.com/dzungtran/echo-rest-api
boilerplate clean-architecture cuelang echo-framework firebase-auth go golang modular opa openpolicyagent rest-api template
Last synced: 29 days ago
JSON representation
A Golang restful API boilerplate based on Echo framework v4. Includes tools for module generation, db migration, authorization, modular, authentication and more.
- Host: GitHub
- URL: https://github.com/dzungtran/echo-rest-api
- Owner: dzungtran
- License: mit
- Created: 2022-04-30T06:02:40.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-01T17:06:56.000Z (6 months ago)
- Last Synced: 2024-07-27T07:33:28.894Z (5 months ago)
- Topics: boilerplate, clean-architecture, cuelang, echo-framework, firebase-auth, go, golang, modular, opa, openpolicyagent, rest-api, template
- Language: Go
- Homepage:
- Size: 532 KB
- Stars: 83
- Watchers: 3
- Forks: 8
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://app.travis-ci.com/dzungtran/echo-rest-api)
[](https://codecov.io/gh/dzungtran/echo-rest-api)
[](https://github.com/dzungtran/echo-rest-api/blob/master/LICENSE)
[](https://pkg.go.dev/github.com/dzungtran/echo-rest-api)
[](https://goreportcard.com/report/github.com/dzungtran/echo-rest-api)
[](https://lgtm.com/projects/g/dzungtran/echo-rest-api/alerts/)
# Echo REST API boilerplate
A Golang restful API boilerplate based on Echo framework v4. Includes tools for module generation, db migration, authorization, authentication and more.
Any feedback and pull requests are welcome and highly appreciated. Feel free to open issues just for comments and discussions.
- [Echo REST API boilerplate](#echo-rest-api-boilerplate)
- [HOW TO USE THIS TEMPLATE](#how-to-use-this-template)
- [Overview](#overview)
- [Features](#features)
- [Running the project](#running-the-project)
- [Swagger Docs](#swagger-docs)
- [Environment variables](#environment-variables)
- [Commands](#commands)
- [Folder Structure](#folder-structure)
- [Open Source Refs](#open-source-refs)
- [Contributing](#contributing)
- [TODOs](#todos)
## HOW TO USE THIS TEMPLATE
> **DO NOT FORK** this is meant to be used from **[Use this template](https://github.com/dzungtran/echo-rest-api/generate)** feature.
1. Click on **[Use this template](https://github.com/dzungtran/echo-rest-api/generate)**
2. Give a name to your project
(e.g. `my_awesome_project` recommendation is to use all lowercase and underscores separation for repo names.)
3. Wait until the first run of CI finishes
(Github Actions will process the template and commit to your new repo)
4. Then clone your new project and happy coding!
> **NOTE**: **WAIT** until first CI run on github actions before cloning your new project.
## Overview
## Features
- [x] User Auth functionality (Signup, Login, Forgot Password, Reset Password, 2FA) using **Firebase Auth**
- [x] REST API using [labstack/echo](https://github.com/labstack/echo).
- [x] DB Migration using [golang-migrate/migrate](https://github.com/golang-migrate/migrate).
- [x] Modular structure.
- [x] Configs via environmental variables.
- [x] Unit tests.
- [x] Dependency injection using [uber-go/dig](https://github.com/uber-go/dig).
- [x] Role based access control using [Open Policy Agent](https://github.com/open-policy-agent/opa).
- [x] Module generation, quickly create model, usecase, api handler.
- [x] CLI support. try: `go run ./tools/mod/ gen` using [spf13/cobra](https://github.com/spf13/cobra).
- [x] Generate API docs using [swaggo](https://github.com/swaggo/swag). Try: `make docs`.
## Running the project
- Make sure you have docker installed.
- Copy `.env.example` to `.env.docker`
- Run `docker compose up -d`.
- Go to `localhost:8088` to verify if the API server works.
## Swagger Docs
To create swagger api documentation you just have to run `make docs`.
after the command executed successfully, run the app and open `http://localhost:8088/docs/index.html` to see swagger documentation page.
## Environment variables
By default, when you run application with `make run-api` command, it will look at `$HOME/.env` for exporting environment variabels.
Setting your config as Environment Variables is recommended as by 12-Factor App.
Variables Defined in the project
| Name | Type | Description | Example value |
|------------------------|---------|------------------------------------------------------------------|-----------------------------------------------|
| DATABASE_URL | string | Data source URL for main DB | postgres://world:hello@postgres/echo_rest_api |
| PORT | integer | Http port (accepts also port number only for heroku compability) | 8088 |
| AUTO_MIGRATE | boolean | Enable run migration every time the application starts | true |
| ENV | string | Environment name | development |
| AUTH_PROVIDER | string | Optional | firebase_auth |
| FIREBASE_CREDENTIALS | json | firebase json admin key | {firebase_admin_key} |
| FIREBASE_AUTH_CREDENTIALS | json | filebase json auth key | {firebase_auth_key} |
## Commands
| Command | Description |
|------------------------------------------|-------------------------------------------------------------|
| `make run-api` | Start REST API application |
| `make build-api` | Build application binary |
| `make setup` | Run commands to setup development env |
| `make run-db` | Run DB docker container on local |
| `go run ./tools/mod/ gen` | Generate module component codes. e.g: `go run ./tools/mod/ gen -n Booking` |
| `make migration-create [migration_name]` | Create migration files. migration_name should be snake case |
| `make git-hooks` | Setup git hooks |
| `make routes` | Generate routes file for authorization |
| `make docs` | Generate API docs |
## Folder Structure
```
.
├── 3rd-parties # Thirdparty configs
├── cmd
│ └── api # Main package of API service
├── config # Application configs struct
│ ...
├── docs # Contains documentation and PlantUML for charts and diagrams
├── domains
├── infrastructure
├── migrations
│ └── sql # Migration files
├── modules
│ ├── core # Core module, includes apis: users, orgs
│ ├── projects # Demo module generation
│ └── shared # To store common usecases and domains which shared between modules
├── out # Output folder of PlantUML
├── pkg
│ ├── authz # Contains Rego rule files for RBAC
│ ├── constants
│ ├── cue # Contains cue files for data validation
│ ...
│ └── utils # Contains helper functions
├── tests
└── tools
├── modtool # Module generation
├── routes # Generate routes file for Authorization
└── scripts # Some helpful bash commands
```
## Open Source Refs
- https://cuelang.org/docs/about/
- https://www.openpolicyagent.org/docs/latest/
- https://echo.labstack.com/guide/
- https://firebase.google.com/docs/auth/admin/
- https://pkg.go.dev/firebase.google.com/go/auth
## Contributing
Please open issues if you want the template to add some features that is not in todos.
Create a PR with relevant information if you want to contribute in this template.
## TODOs
- [x] Update docker compose for ory/kratos.
- [x] Update README.md.
- [x] Update API docs.
- [ ] Replace all cuelang validation by go-playground/validator
- [ ] Remove super admin role and make OPA rules more simpler
- [ ] Write OPA rules to support RBAC for neseted resources
- [ ] Write docs for OPA rules
- [ ] Support simple auth by API Key
- [ ] Add a migration for initial user (require auth with api key)
- [ ] Write acceptence tests (pytest)