README.md

Shurl Express

About

Shurl Express is a web application that allows you to shorten URLs. It was developed as part of a code challenge in a recruitment process.

The Node.js version, as specified in the Dockerfile, is 22.x, which was the latest stable version of Node.js as of the launch of this app. Since this was a development challenge, tsx was used. Therefore, no building of the app is done on the container.

Para uma versão em português do README, acesse o README em português

Requirements

Here are some requirements made by the recruiter, simplified:

• Use latest stable version of Node.js
• Use TypeScript
• Implement token-based authentication, with user registration and login
• Shorten URLs with a maximum length of 6 characters for the slug
• Track the number of times each shortened URL is accessed
• Implement logical deletion of URLs
• Registers must have a update timestamp
• Build endpoints to:
  • Shorten URLs (token optional)
  • Access shortened URLs
  • List shortened URLs by user (token required)
  • Update shortened URLs (token required)
  • Delete shortened URLs (token required)

Extras

• Use Docker Compose to build and run the project
• Implement Swagger documentation
• Configure pre-commit hooks

Setup

1. Clone this repository

git clone https://github.com/GuilhermeCAz/shurl_express.git
cd shurl_express

2. Create a .env file according to .env.example

3. Build the Docker images and run the containers

docker compose up --build --detach

The following command can be used instead:

npm run up

Server should now be accessible at http://localhost:3000.

To stop the server, use the following command:

docker compose down

API Endpoints

Authentication

• POST /register: Register a new user.
• POST /login: Log in and obtain a JWT.

URL Management

• POST /urls: Shorten a URL. Requires valid originalURL in the request body.
• GET /urls: List all URLs associated with the authenticated user.
• PATCH /urls/:slug: Update the original URL for a specific slug. Requires valid originalURL in the request body.
• DELETE /urls/:slug: Logically delete a URL by slug.
• GET /:slug: Redirect to the original URL.

Usage

The following commands can be used to interact with the API. Alternatively, you can use the Swagger UI at http://localhost:3000/docs.

Register User | optional

curl -X 'POST' \
  'http://localhost:3000/register' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "password": "Password123"
}'

Login | optional -> returns JWT

curl -X 'POST' \
  'http://localhost:3000/login' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "user@example.com",
  "password": "Password123"
}'

After logging in, you can use the JWT you received in the Authorization header by adding the following to your request:

-H 'Authorization: Bearer ${JWT}'

This enables associating shortened URLs with the user. Therefore, you are authorized to list, edit and delete URLs shortened by you.

Shorten URL | token optional

curl -X 'POST' \
  'http://localhost:3000/urls' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${JWT}' \
  -H 'Content-Type: application/json' \
  -d '{
  "originalURL": "https://example.com"
}'

List User URLs | token required

curl -X 'GET' \
  'http://localhost:3000/urls' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${JWT}'

Update URL | token required

curl -X 'PATCH' \
  'http://localhost:3000/urls/${slug}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer ${JWT}' \
  -H 'Content-Type: application/json' \
  -d '{
  "originalURL": "https://example.com"
}'

Delete URL | token required

curl -X 'DELETE' \
  'http://localhost:3000/urls/${slug}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer ${JWT}'

Redirect

curl -X 'GET' \
 'http://localhost:3000/${slug}' \
 -H 'accept: */*' \

Note

Swagger UI try it out button does not work for this request due to CORS policy. Use the browser instead.