AdonisJS API Starter

A starter template for AdonisJS API
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Models and Policies
5. Routes
6. Contributing
7. License
8. Contact

About The Project

This project is a starter template for AdonisJS API. It is a simple API with authentication, authorization, and CRUD operations. It has a simple user model with a username, email, and password. Authentication and authorization can be done with bearer token or api keys. It is built with AdonisJS and has a MariaDB database for local development on Docker.

Feel free to use this template for your own projects.

(back to top)

Built With

• AdonisJS
• MariaDB
• Docker
• Yarn
• Prettier

(back to top)

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

• Docker Depending on your host OS, you will need to install docker and docker-compose.

  • docker
  • docker-compose

• Yarn

    npm install --global yarn

Installation

Here is a quick guide to get you started with the project

1. Clone the repo

   git clone [email protected]:vincentdchn/adonis-api-starter.git

2. Install packages

   yarn install

3. Copy the example .env file and file it with your database infos

   cp .env.example .env

   (If you juste want to test the API, you can use the default values of the provided test database)

   PORT=3333
   HOST=0.0.0.0
   NODE_ENV=development
   APP_KEY=lxDZybEmA3itUDz8DQqf290MJC8oos4y
   DRIVE_DISK=local
   DB_CONNECTION=mysql
   MYSQL_HOST=127.0.0.1
   MYSQL_PORT=3306
   MYSQL_USER=user
   MYSQL_PASSWORD=password
   MYSQL_DB_NAME=mydatabase

4. (Optional) If you want to use the provided test database, you can start the container with :

   yarn db:launch

5. Run the migrations with the following command

   yarn db:migrate

(back to top)

Usage

1. Run the development server with

   yarn dev

2. Build the project for production with

   yarn build

(back to top)

Models and Policies

Models

ApiKey

• Belongs to User

• Belongs to Project

• id, userId, projectId, name, key, lastUsedAt, createdAt, updatedAt

Project

• Belongs to User
• Has many ApiKey
• id, userId, name, description, startDate, endDate, createdAt, updatedAt

Role

• id, name, createdAt, updatedAt (There are already two roles coming with the default migrations: admin and user)

User

• Belongs to Role
• Has many Project
• id, roleId, firstname, lastname, email, password, rememberMeToken, createdAt, updatedAt

Policies

ApiKeyPolicy

Actions: list, store, show, update, destroy Conditions: Admin or key/API owner

ProjectPolicy

Actions: list, show, update, destroy Conditions: Admin or project owner

UserPolicy

Actions: index, store, show, update, destroy Conditions: Admin or the user themselves

Note: Policies can be modified in the app/Policies folder. To add a new policy you can refer to the AdoniJS documentation: Policies

(back to top)

Routes

Route	HTTP Method	Controller Action	Description
/api/v1/auth/register	POST	AuthController.register	Register a new user
/api/v1/auth/login	POST	AuthController.login	Login a user
/api/v1/auth/logout	GET	AuthController.logout	Logout a user
/api/v1/users	GET	UsersController.index	Get all users
/api/v1/users	POST	UsersController.store	Create a new user
/api/v1/users/:id	GET	UsersController.show	Get a specific user
/api/v1/users/:id	PUT	UsersController.update	Update a specific user
/api/v1/users/:id	DELETE	UsersController.destroy	Delete a specific user
/api/v1/projects	GET	ProjectsController.index	Get all projects
/api/v1/projects/all	GET	ProjectsController.list	List all projects
/api/v1/projects	POST	ProjectsController.store	Create a new project
/api/v1/projects/:id	GET	ProjectsController.show	Get a specific project
/api/v1/projects/:id	PUT	ProjectsController.update	Update a specific project
/api/v1/projects/:id	DELETE	ProjectsController.destroy	Delete a specific project
/api/v1/keys	GET	ApiKeysController.index	Get all API keys
/api/v1/keys/all	GET	ApiKeysController.list	List all API keys
/api/v1/keys/generate	POST	ApiKeysController.store	Generate a new API key
/api/v1/keys/:id	GET	ApiKeysController.show	Get a specific API key
/api/v1/keys/:id	PUT	ApiKeysController.update	Update a specific API key
/api/v1/keys/:id	DELETE	ApiKeysController.destroy	Delete a specific API key
/api/v1/protected	GET	-	Protected route (auth)
/api/v1/api-key	GET	-	API key route (api-key)

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Vincent Duchêne - @vincentdchn - [email protected]

Project Link: https://github.com/vincentdchn/adonis-api-starter

(back to top)