Have ideas to improve npm?Join in the discussion! »

    @netherium/api-gen
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.3 • Public • Published

    Neth-api-gen

    A powerful RESTful Headless CMS written in Typescript using Express and Angular

    JWT auth, Access-Control Lists (ACL), Uploads, MongoDB, Angular and Angular Material in one 📦

    Lines Covered Build Status Node Version Required Built with Typescript

    Made with by Netherium

    Table of contents

    Quick Start

    1. Npm install globally

      $ npm i -g @netherium/api-gen
    2. 🚀 Launch

      $ neth-api-gen
    3. 💻 Fill in choices

    1. 🙏 If you generated project, navigate and install dependencies

      Server

      $ cd myproject/server
      $ npm install
      $ copy `.env.sample` to `.env` and adjust credentials
      $ npm run dev 

      Navigate to http://localhost:4000/api/auth/init to initialize app

      Client

      $ cd myproject/client
      $ npm install
      $ npm run start (or ng serve)

      Navigate to http://localhost:4200 and login with your credentials

    Admin Panel Login

    All resources are located in the sidenav under Resources

    Admin Panel Sidenav

    Features

    • Typescript Intellisense Awesomeness throughout backend and UI
    • Robust routing and middleware based on same principles of Express
    • Solid modularized admin panel with Angular and Angular Material
    • MongoDB integration
    • Fuzzy search with 'mongoose-fuzzy-searching'
    • Protected routes, ACL based with middleware, using jwt-token
    • File Upload routes and thumbnail generator
    • Test and Coverage
    • REST API Documentation via swagger-ui-express
    • Various helper files and tools, i.e. CORS integration, swagger.yaml, .env environment setup
    • Several scripts for easy development and testing

    Cli Options

    1. 💨 Gimmie my API!!!

      • neth-api-gen
      • Select app
      • Add entities according to your needs
      • Get a production ready(🤞) api + admin panel including basic routes + the entities you've added (ACL required)
      • Impress your team!
    2. 💡 I forgot to add...

      • neth-api-gen
      • Select entities
      • Add more entities to your existing neth-api-gen project, or a solid boilerplate for an ExpressJs/Angular project (modifications may apply)
      • Go and play!
    3. 🕹️ I want more control and faster!!!

      • neth-api-gen -i mysample.json
      • Import all the options from a json file, instead of a UI
      • Do it once, do it many!
    4. 😕 But where is that JSON???

      • neth-api-gen -s
      • Oh yeah, forgot to mention it
    5. Can you help???

      • neth-api-gen -h
      • I can

    ⚠️ When generateApp: true, swaggerDocs is irrelevant, but you need to provide swaggerPath: "myproject/swagger.yaml"

    Develop

    1. 🙏 If you generated project, navigate and install dependencies

      Server

      $ cd myproject/server
      $ npm install

      Client

      $ cd myproject/client
      $ npm install
    2. 🌲 Setup your environment files:

      Server .env, .env.test, .env.production, according to .env.sample (under myproject/server)

      ADDRESS=localhost
      PORT=4000
      MONGODB_URL=mongodb://localhost:27017/YOUDBNAMEHERE
      SECRET=YOURSECRETHERE
      ...

      Client environment.ts, environment.prod.ts (under myproject/client/environments)

      apiUrl: 'http://localhost:4000/api',         // Endpoint of the server
      authorizedRole: ['Admin']                    // Roles that have authorized access to admin panel
      ...
    3. 💨 Develop

      Server

      $ npm run dev

      Client

      $ npm run start (ng serve)
    4. 💡 Initialize: Navigate to http://localhost:4000/api/auth/init

      • 2 Roles will be created, 1 Admin, 1 Public
      • 1 User will be created, based on your .env credentials
      • Resource permissions will be created for basic routes, with default access to admin Role
    5. 🚀 Build!

      Server

      $ npm run build

      Client

      $ npm run build
    6. 🎆Your build is ready to deploy !🎆

    Basic API Routes

    The basic routes provided are listed below. Each one of them is being reflected by its own route, controller, model

    Auth

    • 🔓 api/auth/register [POST]
    • 🔓 api/auth/login [POST]
    • 🔐 api/auth/profile [GET, PUT, DELETE]
    • 🔓 api/auth/init [GET]

    Roles

    • 🔐 api/roles [GET, GET /:id, POST, PUT /:id, DELETE /:id]

    Resource Permissions

    • 🔐 api/resource-permissions [GET, GET /:id, POST, PUT /:id, DELETE /:id]

    Users

    • 🔐 api/users [GET, GET /:id, POST, PUT /:id, DELETE /:id]

    Uploads

    • 🔐 api/uploads [GET, GET /:id, POST, PUT /:id, DELETE /:id]

    Docs

    • 🔓 api/docs [GET]

    Root

    • 🔓 / [GET]

    Endpoints

    • 🔐 api/endpoints [GET]

    Articles (Example Resource Route)

    • 🔐 api/articles [GET, GET /:id, POST, PUT /:id, DELETE /:id]

    Resource Permissions

    • Add a new route with Access-Control List (ACL) by invoking middleware function Auth.getACL() I.e. file article.route.ts
        export class ArticleRoute {
          constructor() {
            this.router.get('/', Auth.getAcl(), controller.list);
            ...
            this.router.post('/', Auth.getAcl(), controller.create);
          }
        }
    • Add the appropriate resource-permission for this resource for each method (list, create, in this case) and for each method the roles that will have access to.
    POST api/resource-permissions
    {
        resourceName: 'articles',
        methods: [
            {
                name: 'list',
                roles: [PublicRoleId]
            },
            {
                name: 'create',
                roles: [AdminRoleId, RegisteredUserRoleId]
            }
        ]
    }

    ⚠️ If you add at least 1 unauthenticated role then this resource route will be open

    Coding Tips

    Get Service

    • Register any service in server.ts, under registerServices function
    • Access it anywhere by destructuring it const {uploadService} = req.app.get('services');

    Get Authenticated User

    • When a route is authenticated, you can access the authenticated user by res.locals.authUser

    Get Resource Permissions

    • For optimization, resource-permissions are stored in app.locals.resourcePermissions. If you update manually a resource (i.e. not via api call, but database manipulation), restart server or call Auth.updateAppPermissions()

    Structure

    Follow the structure below. It will keep things and your mind tidy 🌼

    Server
    .
    ├── dist                # Compiled files ready to deploy `npm run build`
    ├── uploads             # When using local provider this is where uploads go
    │
    ├── src                 # Your code goes here
    │   ├── routes          # Routes that define endpoints, methods, handlers and middleware
    │   ├── controllers     # Controllers that handle functionality from routes
    │   ├── models          # Mongoose models and typescript interfaces
    │   ├── middleware      # Middleware functions
    │   ├── services        # Services in OOP style that can be called in controllers 
    │   ├── helpers         # Exported functions that need no instantiation  
    │   └── server.ts       # Server entrypoint file
    │                       
    ├── test                # Automated tests `npm run test`
    │
    ├── swagger.yaml        # Swagger documentation (`api/docs`) defined in yaml format
    ├── LICENSE             # License file
    └── README.md
    
    Client
    .
    ├── dist                            # Compiled files ready to deploy `npm run build`
    │
    ├── src                             # Your code goes here
    │   ├── app             
    │   │   ├── components              # Shared components throughout the Angular app
    │   │   ├── models                  # Shared models throughout the Angular app    
    │   │   ├── services                # Shared core services throughout the Angular app
    │   │   ├── dialogs                 # Shared dialogs
    │   │   ├── modules                 # Lazy loaded modules, each generated resource corresponds to 1 module
    │   │   └── app-routing.module.ts   # Routing module that binds all lazy loaded modules, each generated resource has a child under `childrenRoutes`  
    │   ├── assets                      # Static resources
    │   ├── environments                # Angular environment configuration
    │   ├── theming                     # Angular Material Theming Styles
    │                      
    ... Rest Default Angular Structure
    

    Uploads

    • Uploads can be stored locally or remotely, see .env
    • To upload a file POST api/uploads with Content-Type: multipart/form-data; or use Postman
    • Field file is the file data, altenativeText, caption are optional strings
    • PUT api/uploads/:id accepts Content-Type: application/json; as only altenativeText, caption can be modified
    • If file of image type, a thumbnail (80x80) will be generated

    Under The Hood

    • When you generate an App, an Express server project based on Neth-express-api-ts and an Angular project are being created

    • When you generate an Entity, multiple files are generated under server and client folders Server

      • Controller, Model, Route files are generated under their corresponding folders ./server/src/controllers/entity.controller.ts, ./server/src/models/entity.model.ts, ./server/src/routes/entity.route.ts
      • An entry in server.ts is created, under method routes

      Client

      • A module is being created under its corresponding folder ./client/src/app/modules/entityfolder/...
      • An entry in app-routing.module.ts is created, under variable childrenRoutes

    Tests

    • Server testing based on Mocha, chai and chai-http
    • Client testing based on the default Angular test tools Jasmine (Tests not provided/generated for Angular, but you can follow standard Angular practices)

    Run tests

    Server

    $ cd myproject/server
    $ npm test

    Client

    $ cd myproject/client
    $ npm test (or ng test)

    Coverage

    Server Coverage is based on nyc

    Run coverage (generated under folder coverage)

    $ npm run test:coverage

    Debug

    To debug TS without compiling it, you can setup your IDE of choice as in the example below
    Note: Running older versions of node may require attaching --inspect before --require

    Authors

    Netherium

    Copyright and license

    Code released under the MIT license

    Install

    npm i @netherium/api-gen

    DownloadsWeekly Downloads

    3

    Version

    0.3.3

    License

    MIT

    Unpacked Size

    699 kB

    Total Files

    255

    Last publish

    Collaborators

    • avatar