qURL

qURL is a simple URL shortening service built with Node.js, Express, and Prisma. It provides an API to shorten URLs, supports custom aliases, and redirects users to the original URLs. It also integrates Prisma as the database ORM for managing shortened URLs.

Features

• Shorten URLs with randomly generated or custom paths.
• Redirect to original URLs using the shortened URL.
• Block access to certain domains.
• JSON-based status API for counting shortened URLs.
• Swagger documentation for easy API exploration.

Tech Stack

• Node.js: Server-side JavaScript runtime.
• Express.js: Web framework for Node.js.
• Prisma: ORM for managing database models and queries.
• SQLite/PostgreSQL/MySQL: Database (You can use any database supported by Prisma).
• Swagger UI: API documentation interface.

Prerequisites

• Node.js (v14.x or higher)
• npm or yarn
• SQLite, PostgreSQL, MySQL, or any other Prisma-supported database
• Prisma (installed via npm)

Installation

1. Clone the repository:

   git clone https://github.com/caliph91/qURL.git
   cd qURL

2. Install dependencies:

   npm install

3. Set up the .env file:

   Copy the example .env file and set your database credentials in the new .env file.

   cp example.env .env

   Example .env for SQLite:

   DATABASE_URL="file:./dev.db"

   Example .env for PostgreSQL:

   DATABASE_URL="postgresql://user:password@localhost:5432/mydatabase?schema=public"

4. Migrate the database schema:

   npx prisma migrate dev --name init

5. Generate Prisma client:

   npx prisma generate

6. Run the development server:

   npm start

   The application will be running at http://localhost:8877.

API Endpoints

1. Create a shortened URL

• GET /api/create
• Query Parameters:
  • url (required): The URL you want to shorten.
  • alias (optional): A custom alias for the shortened URL.

Example:

curl "http://localhost:8877/api/create?url=https://example.com"

Response:

{
  "success": true,
  "error": null,
  "response": {
    "url": "https://example.com",
    "short": "http://localhost:8877/abcd1234"
  }
}

2. Get the status of shortened URLs

• GET /api/status

Example:

curl "http://localhost:8877/api/status"

Response:

{
  "shorten": 100
}

3. Redirect to original URL

• GET /:path

Use the shortened path (/abcd1234) to redirect to the original URL.

Example:

curl -L "http://localhost:8877/abcd1234"

4. Blocked URLs

• If a URL is blocked or if a DNS error occurs, the user is redirected to a /blocked page.

5. Swagger Documentation

• Access the API documentation and test the API with the Swagger UI at:

http://localhost:8877/api-docs

Database

qURL uses Prisma as an ORM. You can easily switch between databases like SQLite, PostgreSQL, or MySQL by changing the DATABASE_URL in your .env file and running the migrations.

Migrate Database

If you modify the schema, you can apply changes by running:

npx prisma migrate dev --name your_migration_name

Prisma Studio

To visually inspect and manage your database, use Prisma Studio:

npx prisma studio

Deployment

1. Heroku

To deploy the app to Heroku, follow these steps:

1. Set up the Prisma environment in Heroku by adding your DATABASE_URL as a config variable.

2. Push your code to Heroku:

   git push heroku master

3. Run migrations on the Heroku server:

   heroku run npx prisma migrate deploy

2. Other Platforms

The app can be deployed on any platform that supports Node.js and Prisma. Just make sure to configure the environment variables (DATABASE_URL) correctly.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Feel free to open issues or pull requests if you'd like to contribute. Any feedback is appreciated!

Acknowledgements

• Prisma
• Express.js
• Node.js
• Swagger UI