Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/guilhermecaz/shurl_express
URL shortening application built with Express. It provides an API for users to create, list, edit and delete short URLs.
https://github.com/guilhermecaz/shurl_express
express rest-api typescript url-shortener
Last synced: 13 days ago
JSON representation
URL shortening application built with Express. It provides an API for users to create, list, edit and delete short URLs.
- Host: GitHub
- URL: https://github.com/guilhermecaz/shurl_express
- Owner: GuilhermeCAz
- License: mit
- Created: 2024-08-15T20:38:53.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-08-17T21:46:10.000Z (5 months ago)
- Last Synced: 2024-08-19T22:33:13.397Z (4 months ago)
- Topics: express, rest-api, typescript, url-shortener
- Language: TypeScript
- Homepage:
- Size: 249 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Shurl Express
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://expressjs.com/)
[](https://www.docker.com/)
[](https://www.postgresql.org/)
[](https://typeorm.io/)
[](https://jwt.io/)
[](https://swagger.io/specification/)
[](https://prettier.io/)
[](https://eslint.org/)
## 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](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](README_pt-br.md)
### 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
```sh
git clone https://github.com/GuilhermeCAz/shurl_express.git
cd shurl_express
```
### 2. Create a `.env` file according to [.env.example](.env.example)
### 3. Build the Docker images and run the containers
```sh
docker compose up --build --detach
```
The following command can be used instead:
```sh
npm run up
```
**Server should now be accessible at `http://localhost:3000`.**
To stop the server, use the following command:
```sh
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`
```sh
curl -X 'POST' \
'http://localhost:3000/register' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"password": "Password123"
}'
```
### Login | `optional` -> returns JWT
```sh
curl -X 'POST' \
'http://localhost:3000/login' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"email": "[email protected]",
"password": "Password123"
}'
```
After logging in, you can use the JWT you received in the Authorization header by adding the following to your request:
```sh
-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`
```sh
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`
```sh
curl -X 'GET' \
'http://localhost:3000/urls' \
-H 'accept: application/json' \
-H 'Authorization: Bearer ${JWT}'
```
### Update URL | `token required`
```sh
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`
```sh
curl -X 'DELETE' \
'http://localhost:3000/urls/${slug}' \
-H 'accept: */*' \
-H 'Authorization: Bearer ${JWT}'
```
### Redirect
```sh
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.