Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/emmanuel-owusu/shortlink
ShortLink is a URL-shortening service
https://github.com/emmanuel-owusu/shortlink
docker gradle java spring springboot springmvc springweb
Last synced: 2 days ago
JSON representation
ShortLink is a URL-shortening service
- Host: GitHub
- URL: https://github.com/emmanuel-owusu/shortlink
- Owner: emmanuel-owusu
- License: mit
- Created: 2024-05-09T21:01:29.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-05-13T09:54:32.000Z (6 months ago)
- Last Synced: 2024-10-13T02:40:57.352Z (about 1 month ago)
- Topics: docker, gradle, java, spring, springboot, springmvc, springweb
- Language: Java
- Homepage:
- Size: 93.8 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ShortLink ✨🔗
[](https://www.oracle.com/java/technologies/downloads/#java21)
[](https://spring.io/projects/spring-boot)
[](LICENSE)
## About ShortLink
ShortLink is a URL-shortening service.
* [Quick Start](#quick-start)
* [Run as Spring Application](#run-as-spring-app)
* [Using the ShortLink Service](#using-the-shortlink-service)
* [Run Unit Tests](#run-unit-test)
* [Run as Docker Container](#run-as-docker-container)
* [Viewing the API Documentation](#api-documentaion)
* [Additional Design Considerations](#design-considerations)
* [Built With](#frameworks)
* [Project Links](#project-links)
### Run as Spring Application
This section guides developers on launching the ShortLink URL-shortening service as a standalone Spring application.
**Prerequisites:**
* Git installed on your system
* Java Development Kit (JDK) 11 or above
**Steps:**
1. **Clone the Project:**
```bash
git clone [email protected]:emmanuel-owusu/shortlink.git
```
2. **Build and Run the Application:**
Navigate to the project root directory and execute the following command:
```bash
./gradlew bootRun
```
This command downloads dependencies, builds the application, and starts it as a Spring Boot application.
3. **Verify Application Health (Optional):**
Once the application starts, you can verify its health using a tool like CURL:
```bash
curl http://localhost:8080/actuator/health
```
A successful response indicates the application is running properly.
```json
{
"status": "UP"
}
```
Follow the steps in the '[Using the ShortLink Service](#using-the-shortlink-service)' section for more details on using the service once it's running.
### Using the ShortLink Service
The ShortLink service exposes two main functionalities:
* **Encoding URLs (Shortening)**:
* The `/service/shortlink/encode` endpoint accepts a URL as a query parameter named `url`.
* The request should use URL encoding for the `url` parameter.
**Example Encode Request:**
```bash
curl --get --data-urlencode "url=https://en.wikipedia.org/wiki/Astronomy" http://localhost:8080/service/shortlink/encode
```
**Example Encode Response (JSON):**
```json
{
"data": {
"original_url": "https://en.wikipedia.org/wiki/Astronomy",
"short_url": "http://short.link/000000"
},
"message": "URL shortened successfully.",
"status": "success"
}
```
* **Decoding URLs (Expanding):**
* The `/service/shortlink/decode` endpoint accepts a shortened URL as a query parameter named `url`.
* The request should use URL encoding for the `url` parameter.
**Example Decode Request:**
```bash
curl --get --data-urlencode "url=http://short.link/000000" http://localhost:8080/service/shortlink/decode
```
**Example Decode Response (JSON):**
```json
{
"data": {
"original_url": "https://en.wikipedia.org/wiki/Astronomy",
"short_url": "http://short.link/000000"
},
"message": "original URL retrieved successfully.",
"status": "success"
}
```
**Additional Notes:**
* Replace http://short.link/000000 with the actual shortened URL returned by the service in your responses.
### Run Unit Tests
This project uses JUnit for unit testing. To run the tests, follow these steps:
1. **Prerequisites:**
* Ensure you have Java installed and configured on your system. You can verify this by running `java -version` in your terminal.
* Make sure you have Gradle set up for dependency management.
2. **Run Tests:**
* Open a terminal and navigate to your project directory.
* Run `gradle test`:
```bash
./gradlew test
```
3. **View Results:**
* The test results will be displayed in the terminal, indicating successful or failed tests and any associated error messages.
* To view the HTML test result files, navigate to: `path_to_your_project/module_name/build/reports/tests/` directory.
### Run as Docker Container
Here's how to quickly build and run the ShortLink URL-shortening service in a Docker container:
**Prerequisites:**
* Docker installed on your system
* Install: https://www.docker.com/products/docker-desktop/
* Check if installed: `docker --version`
* Git installed on your system
* Install: https://git-scm.com/downloads
* Check if installed: `git --version`
**Steps:**
1. **Clone the Project:**
```bash
git clone [email protected]:emmanuel-owusu/shortlink.git
```
2. **Navigate to the Project Directory:**
Navigate to the project root directory and execute the following command:
```bash
cd shortlink
```
3. **Build the Docker Image**:
This builds a Docker image named `shortlink` based on the included Dockerfile:
```bash
docker build -t shortlink .
```
4. **Run the Application:**
This starts a container from the shortlink image, exposes port 8080, and runs the application in the background:
```bash
docker run -d --name shortlink_container -p 8080:8080 shortlink
```
5. **Verify Application Health (Optional):**
Once the container is running, you should be able to access the ShortLink service through your web browser at http://localhost:8080/actuator/health.
A successful response indicates the application is running properly.
```json
{
"status": "UP"
}
```
Follow the steps in the '[Using the ShortLink Service](#using-the-shortlink-service)' section for more details on using the service once it's running.
### Viewing the API Documentation
This API provides an interactive Swagger UI for exploring available endpoints and their details. To access the documentation:
1. **Start the Application:** Ensure your Spring application is running.
2. **Open the Swagger UI:** Navigate to http://localhost:8080/swagger-ui/index.html in your web browser, replacing port `8080` with the port your application is running on (usually 8080 by default).
The Swagger UI will display a comprehensive view of your API, including:
* **List of Endpoints:** Explore all available API endpoints with clear descriptions.
* **Detailed Information:** View detailed information for each endpoint, including request parameters, response structures, and supported HTTP methods.
* **Interactive Testing:** The UI allows you to directly test API calls with various parameters and view the corresponding responses.
This interactive documentation should provide a clear understanding of how to interact with the API and its functionalities.
## Additional Design Considerations
This is a simple implementation for demonstration purposes. For a production-ready URL shortener, consider:
* Persistence & Scalability: Store URL mappings in a scalable database like MySQL or Redis for high availability.
* Conflict Resolution: Implement strategies like adding random characters to the shortcode to handle collisions during generation.
* Security:
* Validate user input to prevent malicious URLs.
* Implement rate limiting to avoid abuse.
* Consider password protection for managing shortened links (optional).
## Built With
* [Spring Boot 3.2.5 with Spring Web](https://start.spring.io/#!type=gradle-project&language=java&platformVersion=3.2.5&packaging=jar&jvmVersion=21&groupId=com.github.emmanuel-owusu&artifactId=shortlink&name=ShortLink&description=ShortLink%20is%20a%20URL%20shortening%20service&packageName=com.github.emmanuel-owusu.shortlink&dependencies=web)
* [Java 21](https://www.oracle.com/java/technologies/downloads/#java21)
* [OpenAPI Specification (OAS) / Swagger](https://www.openapis.org/)
* [Docker](https://www.docker.com/)
[](https://www.oracle.com/java/)
[](https://spring.io/)
[](https://www.docker.com/)
## Project Links
* Author Profile - [github.com/emmanuel-owusu](https://github.com/emmanuel-owusu)
* Code Repository - [https://github.com/emmanuel-owusu/shortlink](https://github.com/emmanuel-owusu/shortlink)