MagicBrain API

An API for MagicBrain, a modern web application which identifies faces in images and display its boundaries.
Explore the docs »

API in Production · Report Bug / Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Endpoints
5. Roadmap
6. Contributing
7. Contact
8. Acknowledgements

About The Project

Back-End API for MagicBrain, a modern web application which identifies faces in images and display its boundaries.

This project was originally built as part of a Full Stack pratical exercise, aimed at learning how to build a REST API using Javascript, Node and Express and PostgreSQL database.

Built With

MagicBrain API was built with the following technologies:

Getting Started

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

Prerequisites

Have npm installed in your machine.

• npm

  npm install npm@latest -g

• Clarifai API Key -> Get yours HERE
• Postgres installed and running locally -> Download it HERE

Installation

On terminal

1. Clone the repo

   git clone https://github.com/sgtbrunner/magicbrain-api

2. Navigate to project folder

   cd magicbrain-api

3. Install NPM packages

   npm install

4. Create a local postgres database

   createdb 'your-database'

5. Inside your newly created database, add two tables with the following scripts:

    CREATE TABLE users {
        id serial PRIMARY KEY,
        name VARCHAR(100),
        email text UNIQUE NOT NULL,
        entries BIGINT DEFAULT,
        joined TIMESTAMP NOT NULL
    };
   

   and

    CREATE TABLE login {
        id serial PRIMARY KEY,
        hash varchar(100) NOT NULL,
        email text UNIQUE NOT NULL
    };
   

6. Create a config.js file in the project root folder and export your API KEY:

   const API_KEY = // your api key
   
   module.exports = {
       API_KEY,
   }
   

7. Setup your personal database info in database.js as:

   const DEV_DB_CONNECTION = {
     host: '127.0.0.1',
     user: '', // your master local db user name
     password: '', // the local database password
     database: 'your-database', // the local dabatase name
   }
   

Usage

The MagicBrain API doesn't have authentication.
Run the following commands on terminal within the project folder:

1. Starting the app

   npm run start:dev

   The project should be served at:

   http://localhost:5000/

   Alternatively, you can try out the API in PRODUCTION:

   https://mighty-beyond-04256.herokuapp.com

Endpoints

Get Server status

GET /

Example

Input: No Input for this endpoint
Output: server is working!!!!

Get single user

GET /profile/{id}

Example

Input:

• id: user's id

Output:

 {
   "id": 2,
   "name": "test",
   "email": "test@test.com",
   "entries": "1",
   "joined": "2021-05-18T01:18:12.131Z"
 }

Errors:

 "HTTP ERROR STATUS 404 - User id 1 not found"

Sign-In users

POST /signin

Example

Body Input:

{
  "email": "test@email.com",
  "password": "testtest"
}

Output:

 {
   "id": 20,
   "name": "test",
   "email": "test@email.com",
   "entries": "11",
   "joined": "2021-05-18T01:18:12.131Z"
 }

Errors:

{
 "error": "You have entered an invalid username and/or password"
}

Register users

POST /register

Example

Body Input:

{
  "name": "test",
  "email": "admin@test.com",
  "password": "fasfasf56"
}

Output:

{
   "id": 5,
   "name": "test",
   "email": "admin@test.com",
   "entries": "0",
   "joined": "2021-08-13T15:17:00.125Z"
}

Errors:

{
 "error": "Email \"admin@test.com\" already registered."
}

Register users

POST /register

Example

Body Input:

{
  "name": "test",
  "email": "admin@test.com",
  "password": "fasfasf56"
}

Output:

{
   "id": 5,
   "name": "test",
   "email": "admin@test.com",
   "entries": "0",
   "joined": "2021-08-13T15:17:00.125Z"
}

Errors:

{
 "error": "Email \"admin@test.com\" already registered."
}

Update entries

PUT /image

Example

Body Input:

{
  "id": "5",
}

Output:

{
   "count": 6,
}

Errors:

{
 "error": "Unable to update your image count. Please try again later"
}

Checks image for face-recognitiones

POST /imageurl

Example

Body Input:

{
  "input": "https://www.aceshowbiz.com/images/photo/the_rock.jpg"
}

Output:

{
 "status": {
     "code": 10000,
     "description": "Ok",
     "req_id": "32736d634ba346df81879affa5fb5daa"
 },
 "outputs": [
     {
         "id": "af88b1bb78014896b0bcbc6d5273e117",
         "status": {
             "code": 10000,
             "description": "Ok"
         },
         "created_at": "2021-08-13T16:46:05.322537140Z",
         "model": {
             "id": "a403429f2ddf4b49b307e318f00e528b",
             "name": "face",
             "created_at": "2016-10-25T19:30:38.541073Z",
             "app_id": "main",
             "output_info": {
                 "output_config": {
                     "concepts_mutually_exclusive": false,
                     "closed_environment": false,
                     "max_concepts": 0,
                     "min_value": 0
                 },
                 "message": "Show output_info with: GET /models/{model_id}/output_info",
                 "type": "detect-concept",
                 "type_ext": "detect-concept"
             },
             "model_version": {
                 "id": "34ce21a40cc24b6b96ffee54aabff139",
                 "created_at": "2019-01-17T19:45:49.087547Z",
                 "status": {
                     "code": 21100,
                     "description": "Model is trained and ready"
                 },
                 "visibility": {
                     "gettable": 10
                 },
                 "app_id": "main",
                 "user_id": "clarifai",
                 "metadata": {}
             },
             "display_name": "Face Detection",
             "user_id": "clarifai",
             "input_info": {},
             "train_info": {},
             "model_type_id": "visual-detector",
             "visibility": {
                 "gettable": 10
             },
             "metadata": {}
         },
         "input": {
             "id": "2b660a8308a944e5a75a2d96806985fe",
             "data": {
                 "image": {
                     "url": "https://www.aceshowbiz.com/images/photo/the_rock.jpg"
                 }
             }
         },
         "data": {
             "regions": [
                 {
                     "id": "b055216dba030ca1944c06937ccdadd6",
                     "region_info": {
                         "bounding_box": {
                             "top_row": 0.05029705,
                             "left_col": 0.32780963,
                             "bottom_row": 0.6298665,
                             "right_col": 0.7165285
                         }
                     },
                     "data": {
                         "concepts": [
                             {
                                 "id": "ai_8jtPl3Xj",
                                 "name": "face",
                                 "value": 0.99990416,
                                 "app_id": "main"
                             }
                         ]
                     },
                     "value": 0.99990416
                 }
             ]
         }
     }
 ],
 "rawData": {
     "status": {
         "code": 10000,
         "description": "Ok",
         "req_id": "32736d634ba346df81879affa5fb5daa"
     },
     "outputs": [
         {
             "id": "af88b1bb78014896b0bcbc6d5273e117",
             "status": {
                 "code": 10000,
                 "description": "Ok"
             },
             "created_at": "2021-08-13T16:46:05.322537140Z",
             "model": {
                 "id": "a403429f2ddf4b49b307e318f00e528b",
                 "name": "face",
                 "created_at": "2016-10-25T19:30:38.541073Z",
                 "app_id": "main",
                 "output_info": {
                     "output_config": {
                         "concepts_mutually_exclusive": false,
                         "closed_environment": false,
                         "max_concepts": 0,
                         "min_value": 0
                     },
                     "message": "Show output_info with: GET /models/{model_id}/output_info",
                     "type": "detect-concept",
                     "type_ext": "detect-concept"
                 },
                 "model_version": {
                     "id": "34ce21a40cc24b6b96ffee54aabff139",
                     "created_at": "2019-01-17T19:45:49.087547Z",
                     "status": {
                         "code": 21100,
                         "description": "Model is trained and ready"
                     },
                     "visibility": {
                         "gettable": 10
                     },
                     "app_id": "main",
                     "user_id": "clarifai",
                     "metadata": {}
                 },
                 "display_name": "Face Detection",
                 "user_id": "clarifai",
                 "input_info": {},
                 "train_info": {},
                 "model_type_id": "visual-detector",
                 "visibility": {
                     "gettable": 10
                 },
                 "metadata": {}
             },
             "input": {
                 "id": "2b660a8308a944e5a75a2d96806985fe",
                 "data": {
                     "image": {
                         "url": "https://www.aceshowbiz.com/images/photo/the_rock.jpg"
                     }
                 }
             },
             "data": {
                 "regions": [
                     {
                         "id": "b055216dba030ca1944c06937ccdadd6",
                         "region_info": {
                             "bounding_box": {
                                 "top_row": 0.05029705,
                                 "left_col": 0.32780963,
                                 "bottom_row": 0.6298665,
                                 "right_col": 0.7165285
                             }
                         },
                         "data": {
                             "concepts": [
                                 {
                                     "id": "ai_8jtPl3Xj",
                                     "name": "face",
                                     "value": 0.99990416,
                                     "app_id": "main"
                                 }
                             ]
                         },
                         "value": 0.99990416
                     }
                 ]
             }
         }
     ]
 }
}

Errors:

{
 "error": "Unable to detect faces on selected image. Please check your url and try again."
}

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

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

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

Contact

Guilherme Brunner - guilherme.brunner@gmail.com

Project Link: https://github.com/sgtbrunner/magicbrain-api

Acknowledgements

• bcrypt
• cors
• dotenv
• knex
• pg
• Clarifai API
• Moment.js
• Heroku