{"id":13656581,"url":"https://github.com/zmts/supra-api-nodejs","last_synced_at":"2025-04-06T06:13:06.914Z","repository":{"id":25982058,"uuid":"107028330","full_name":"zmts/supra-api-nodejs","owner":"zmts","description":"❤️ Node.js REST API boilerplate. Old but still good for references","archived":false,"fork":false,"pushed_at":"2023-03-04T05:51:35.000Z","size":5240,"stargazers_count":346,"open_issues_count":8,"forks_count":92,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-03-30T05:07:19.189Z","etag":null,"topics":["access-token","api","architecture","cookies","express-boilerplate","framework-agnostic","jwt","nodejs","nodejs-api","objectionjs","postgresql","refresh-token","restful","sql","starter-kit","tests"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/zmts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-15T16:20:52.000Z","updated_at":"2025-03-26T13:14:51.000Z","dependencies_parsed_at":"2024-08-02T05:02:50.258Z","dependency_job_id":"22fd3a63-c9e1-4280-a695-31403eff4e3c","html_url":"https://github.com/zmts/supra-api-nodejs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmts%2Fsupra-api-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmts%2Fsupra-api-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmts%2Fsupra-api-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zmts%2Fsupra-api-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zmts","download_url":"https://codeload.github.com/zmts/supra-api-nodejs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441059,"owners_count":20939239,"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":["access-token","api","architecture","cookies","express-boilerplate","framework-agnostic","jwt","nodejs","nodejs-api","objectionjs","postgresql","refresh-token","restful","sql","starter-kit","tests"],"created_at":"2024-08-02T05:00:24.070Z","updated_at":"2025-04-06T06:13:06.875Z","avatar_url":"https://github.com/zmts.png","language":"JavaScript","readme":"# Node.js API boilerplate\n\nPiece of my thoughts about Node.js architecture.\n\n[supra-api-nodejs: A little bit about Node.js RESTful APIs Architecture (RU)](https://gist.github.com/zmts/6ac57301e2e8e8e9e059e9c087732c05)\n\n## Highlights:\n- Modular RESTful API\n- ES6 Classes\n- Action based\n- SQL based (PostgreSQL with objection.js)\n- Migrations(knex.js)\n- Auth (JWT/Access-token/Refresh-token)\n- Cookie support\n- Role based access control\n- Request validation\n- CRUD(users, posts resources)\n- Automated API documentation\n- Full authentication/authorization and user registration flow implemented\n- Tests(e2e)\n\n## Key points:\n### 0. Monolith first\nSupra-api-nodejs its about monolith first approach. But this does not prevent you from using it in a microservice architecture as well.\n\n### 1. Controller layer\nEach entity have own controller class it slim layer representing resource mapping(routing) \n```\nclass PostsController extends BaseController {\n  static get router () {\n    router.get('/', this.actionRunner(actions.ListAction))\n    router.get('/:id', this.actionRunner(actions.GetByIdAction))\n    router.post('/', this.actionRunner(actions.CreateAction))\n    router.patch('/:id', this.actionRunner(actions.UpdateAction))\n    router.delete('/:id', this.actionRunner(actions.RemoveAction))\n\n    return router\n  }\n}\n``` \nFor example `PostsController` implements `post` entity routes. Each route fires own `action`. \n\n### 2. Action layer\nIt's a class encapsulated request validation, permission verification and business logic. One file, one class, one REST operation, one use case.\n\n### 3. DAO layer\nImplement data access methods.\n\n### 4. Model layer\nRepresent models schemas and validation rules. There is no other logic __only model fields and validation rules__.\n## Development:\n\n### Install global dependencies:\n```\nnpm i -g knex nodemon\n```\n### Setup database:\n1. Install PostgreSQL (https://postgresapp.com/downloads.html (for Mac OS))\n2. Create some DB (https://eggerapps.at/postico/ (for Mac OS))\n\n### Go ahead...\n```\ncd /supra-api-nodejs\n```\n- `cp .env.example .env`\n- Set required credential in `.env` \n\nRun migration to set base SQL schema\n```\nknex migrate:latest\n```\n\nRun server\n```\nnpm run start // prod mode\nnpm run dev // dev mode\n```\n\n### Implemented endpoints:\n\n#### /auth\nPath | Method | Description\n---|---|---\n/auth/login | POST | LoginAction\n/auth/logout | POST | LogoutAction\n/auth/refresh-tokens | POST | RefreshTokensAction\n\n#### /users\nPath | Method | Description\n---|---|---\n/users | GET | ListUsersAction\n/users/current | GET | GetCurrentUserAction\n/users/:id | GET | GetUserByIdAction\n/users | POST | CreateUserAction\n/users | PATCH | UpdateUserAction\n/users/:id | DELETE | RemoveUserAction\n/users/change-password | POST | ChangePasswordAction\n/users/send-reset-password-email | POST | SendResetPasswordEmailAction\n/users/reset-password | POST | ResetPasswordAction\n/users/confirm-registration | POST | ConfirmRegistrationAction\n/users/change-email | POST | ChangeEmailAction\n/users/confirm-email | POST | ConfirmEmailAction\n/users/resend-confirm-new-email-token | POST | ResendConfirmNewEmailTokenAction\n/users/cancel-email-changing | POST | CancelEmailChangingAction\n\n#### /posts\nPath | Method | Description\n---|---|---\n/posts | GET | ListPostsAction\n/posts | POST | CreatePostAction\n/posts/:id | GET | GetPostByIdAction\n/posts/:id | PATCH | UpdatePostAction\n/posts/:id | DELETE | RemovePostAction\n\n__!!! Project still in progress !!!__\n\n_2017 - 2018 - 2019 - 2020 ..._\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmts%2Fsupra-api-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzmts%2Fsupra-api-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzmts%2Fsupra-api-nodejs/lists"}