Shortgun - URL shortener service

Shortgun provides REST API for URL shortener service building. It includes account creation, authorization, CRUD operations for URL shortcuts and additional features such as saving messages from users.

This project built for learning purposes. Do not use it for business-critical or other essential tasks.

Requirements

• Latest LTS or current installation of Node.js (tested on 13.8.0)
• MongoDB server up and running
• Nginx or another web-server up and running for serving page preview thumbnails and proxy requests
• Git installed

Installation

1. Clone this repository to local machine

git clone https://github.com/konrad-molitor/shortgun.git

2. Navigate to shortgun directory

cd shortgun

3. Perform dependecies installation

npm install

4. Build project

npm run build

5. Navigate to build directory

cd build

6. Create .env file.

   .env file shoult contain following information:

   • MongoDB connection string (https://docs.mongodb.com/manual/reference/connection-string/)

   DB_URL=<mongodb_connection_string>

   • JsonWebToken secret key string

   SECRET_KEY=<jwt_secret_key>

   • Thumbnails directory path (make sure that user running this app has write permission to it)

   THUMBNAILS_PATH=<thumbnails directory full path>

7. Configure your web server to host thumnails directory to /images path

8. Configure your web server to proxy requests all requests to /a to desired port/URL

9. Set your process.env.PORT variable to desired port (this also can be done using .env file)

10. Run build/app.js

node app.js

I suggest using process management software such as pm2, IBM StrongLoop, Forever or systemd

API

Routes list

API provides following routes:

/a/
 signup
 login
 profile
 item/<itemId>
 message
 add
/s/
 <shortcut>

/a/signup

Route for creating a new user account

Parameters:

HTTP Verb:

• POST

Headers:

• Content-Type required - must be application/json

Request body:

• email required String - new user email
• password required String - new user password

Returns:

HTTP Status:

• 409 - if user already exists (no data saved in DB)
• 500 - Server error
• 200 - New account created

Response body:

• User already exists - if user already exists
• Error - if server error occured
• <email> - created user email

/a/login

Login route

Parameters:

HTTP Verb:

• POST

Headers:

• Content-Type required must be application/json

Request body:

• email required String - user email
• password required String - user password

Returns:

HTTP Status:

• 403 - Authentication failed
• 500 - Server error
• 200 - Login successful

Response body:

• No such user. - provided email does not exist in database
• Invalid password. - provided password does not match stored in database for provided email
• Server error - server error occured during processing the request
• <token> - JWT token

/a/profile

Profile data route

Parameters:

HTTP Verb:

• GET

Headers:

• X-Auth required - must contain user token in format Bearer:<space><usertoken> as this: Bearer: thisIsUser.Token

Returns:

HTTP Status:

• 400 - Incorrect request headers
• 401 - Incorrect or missing token
• 500 - Server error
• 200 - OK

Response body:

• Server error - server error occured during processing the request
• Invalid token. - Token was processed, but no according records were found in database
• Incorrect request headers. - Token can not be processed
• Authorization required - No X-Auth header present in request
• [Object] JSON user object in following format:

{
    _id: <userId>,
    email: <userEmail>,
    urls: [
        {
            longUrl: <longUrl>, //long URL string
            shortUrl: <shortUrl>, //shortcut string
            _id: <shortcutId>,
            preview: <previewImage>, //only filename
            pageTitle: <pageTitle> //original page title
        }
    ]
}

/a/item/<itemId>

Shortcut item managing route

Example: /a/item/5e3ec5f2a986c875e30d088f

Parameters:

HTTP Verb:

• DELETE

Headers:

• X-Auth required - must contain user token in format Bearer:<space><usertoken> as this: Bearer: thisIsUser.Token

URL parameters:

• <itemId> required - shortcut item id.

Returns:

HTTP Status:

• 400 - Incorrect request headers or invalid item ID
• 401 - Incorrect or missing token, attempt to delete another user shortcut
• 404 - Shortcut ID not found
• 500 - Server error
• 200 - OK

Response body:

• Server error - server error occured during processing the request

• Only shortcut author can delete it. - attempt to delete another user shortcut

• No such shortcut. - shortcut with such ID not found

• Authorization required - Token invalid or missing

• Invalid item ID - provided item ID is invalid

• [Object] - Deleted item in following format:

  {
      longUrl: <longUrl>, //long URL string
      shortUrl: <shortUrl>, //shortcut string
      _id: <shortcutId>,
      preview: <previewImage>, //only filename
      pageTitle: <pageTitle> //original page title
  }
  

/a/message

Route for direct messaging server owner

Parameters:

HTTP Verb:

• POST

Headers:

• Content-Type required must be application/json
• X-Auth - may contain user token in format Bearer:<space><usertoken> as this: Bearer: thisIsUser.Token

Request body:

• email required String sender email
• message required String message body

Returns:

HTTP Status:

• 204 - Message successfully created
• 500 - Server error

/a/add

Route for adding shortcuts

Parameters

HTTP Verb:

• POST

Headers:

• Content-Type required must be application/json
• X-Auth required - must contain user token in format Bearer:<space><usertoken> as this: Bearer: thisIsUser.Token

Request body:

• longUrl required String - desired URL for creating shortcut

Returns:

HTTP Status:

• 401 - Authentication failed
• 500 - Server error
• 200 - OK

Response body:

• [Object] - created item in following format:

  {
      longUrl: <longUrl>, //long URL string
      shortUrl: <shortUrl>, //shortcut string
      _id: <shortcutId>,
      preview: <previewImage>, //only filename
      pageTitle: <pageTitle> //original page title
  }
  

/s/<shortUrl>

Redirect to original URL path

Parameters:

HTTP Verb:

• GET

Returns:

HTTP Status:

• 302 - Found

Headers:

• Location - original URL location.

  Will redirect to / if shortcut not found

Content format

Essentially, shortgun operates only few content unit types: User, Shortcut and Message.

User

User profile record

Fields:

• email required unique String - user email. For authentication purposes only (for now)
• password required String - user password. Stored as hash with help of bcrypt library.
• urls [ObjectID] - an array containing user created shortcuts IDs

Shortcut

Shortcut item record

Fields:

• longUrl required String - original URL
• shortUrl unique String - shortcut string (without actual URL, it's up to client to form full link URL)
• author required ObjectID - shortcut author record ID
• preview String - preview image filename (without path)
• pageTitle String - page title of original URL

Message

Messages to site owner format

Fields:

• email required String - sender email
• message required String - message body
• user String - not implemented yet

Preview images

Previews are generated during shortcut creation. Hovewer, preview generation takes some time, so initially server will send shortcut item without preview and pageTitle fields. They will appear later, as preview generation process will finish.

Previews are stored in JPEG format with filename format <shortcutId>.jpg. Original page screenshots are taken with viewport size 1280x720 px and then resized to 400x225 px.

Contributing

PRs are welcome. For major changes, please open an issue first to discuss what you would like to change. https://www.firsttimersonly.com/ - friendly.

License

Unless stated elsewhere, file headers or otherwise, the license as stated in the LICENSE file.