{"id":13630044,"url":"https://github.com/smallcase/smalllinks","last_synced_at":"2025-10-26T07:31:12.412Z","repository":{"id":45913449,"uuid":"364523960","full_name":"smallcase/smalllinks","owner":"smallcase","description":"Simple URL shortener built with Fastify. Uses PostgreSQL, Redis, and Kafka.","archived":false,"fork":false,"pushed_at":"2021-11-28T23:18:47.000Z","size":1032,"stargazers_count":112,"open_issues_count":2,"forks_count":6,"subscribers_count":5,"default_branch":"development","last_synced_at":"2025-01-31T16:51:33.122Z","etag":null,"topics":["docker-compose","fastify","hacktoberfest","kafka","nanoid","postgresql","redis","url-shortener"],"latest_commit_sha":null,"homepage":"https://www.smallcase.com/blog/open-sourcing-url-shortener/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smallcase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2021-05-05T09:25:53.000Z","updated_at":"2024-08-14T09:51:58.000Z","dependencies_parsed_at":"2022-09-24T18:43:48.768Z","dependency_job_id":null,"html_url":"https://github.com/smallcase/smalllinks","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallcase%2Fsmalllinks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallcase%2Fsmalllinks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallcase%2Fsmalllinks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smallcase%2Fsmalllinks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smallcase","download_url":"https://codeload.github.com/smallcase/smalllinks/tar.gz/refs/heads/development","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238284799,"owners_count":19446731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker-compose","fastify","hacktoberfest","kafka","nanoid","postgresql","redis","url-shortener"],"created_at":"2024-08-01T22:01:28.314Z","updated_at":"2025-10-26T07:31:06.940Z","avatar_url":"https://github.com/smallcase.png","language":"JavaScript","readme":"\u003cdiv\u003e\n\u003cimg src=\"./url-shortener.png\" width=\"400px\" height=\"200px\"\u003e\n\u003c/div\u003e\n\n# URL Shortener\n\n![GitHub issues](https://img.shields.io/github/issues/smallcase/smalllinks)\n[![MIT License](https://img.shields.io/apm/l/atomic-design-ui.svg?)](https://github.com/tterb/atomic-design-ui/blob/master/LICENSEs)\n\nA simple URL shortener utility built with Nodejs, PostgreSQL, Redis and Kafka.\n\n\n## Installation \n\n### Without Docker\n\n- Clone the project\n\n```\ngit clone git@github.com:smallcase/smalllinks.git\ncd smalllinks\n```\n\n- Install the dependencies\n\n```\nnpm install\n```\n\n- Source the environment variables present in `.example.env`. When running on local, make sure that PostgreSQL, Kafka and Redis are available \u0026 running.\n\n```\nsource .example.env\n```\n\n- Then, you can run the server\n\n```\nnpm start\n```\n\nor, you can run the server on dev with live reload\n\n```\nnpm run dev\n```\n\nOpen http://localhost:8201/status with your favorite browser to check the status of the service.\n\n### Using Docker\n\n`.example.env` file is used for environment variables. No changes are required in the env file to run with docker.\n\nThen, run this in the project root level:\n\n```\ndocker-compose up\n```\n\nThe app will be running at http://localhost:8201, you'll be test out the service by visiting the swagger API docs at http://localhost:8201/api-docs\n \n## Running Tests\n\nTo run tests, run the following command\n\n```bash\n  npm run test\n```\n\n## Usage/Examples\n\n### To get the short URL\n\n```bash\n$ curl -d '{\"url\": \"\u003cLONG-URL\u003e\"}' -H 'Content-Type: application/json' \u003cBASE_URL\u003e/shortenUrl\n```\n\nor, you can explicitly provide the TTL (time-to-live) for the short URL. By default, TTL is set to 2 years ahead.\n\n```bash\n$ curl -d '{\"url\": \"\u003cLONG-URL\u003e\", \"ttl\": \"2020-12-25\"}' -H 'Content-Type: application/json' \u003cBASE_URL\u003e/shortenUrl\n```\n\nResponse:\n\n```json\n{\n    \"shortUrl\":\"\u003cSHORT-URL\u003e\",\n    \"longUrl\":\"\u003cLONG-URL\u003e\"\n}\n```\n\n### To get the long URL\n\n```bash\n$ curl -i -H 'Content-Type: application/json' \u003cBASE_URL\u003e/\u003cSHORT-URL\u003e\n```\n\nResponse:\n\n```\nHTTP/1.1 302 OK\nDate: Thu, 02 Jul 2020 10:31:09 GMT\nTransfer-Encoding: chunked\nConnection: keep-alive\nLocation: \u003cLONG-URL\u003e\n```\n\nAlternatively, you can use swagger API to test out the functionality:\n  \n## Using Swagger API\n\nYou can run the project locally by using the `Installation` steps mentioned above and head over to `/api-docs` to see the Swagger UI.\n\n![URL Shortener Swagger UI](url-shortener-swagger-ui.png)\n\nYou can use it to generate new short URLs as well test the redirection.\n\nHowever, two things to note while using Swagger UI to test out the functionality:\n\n1. While redirection is capable of working through Swagger UI itself, there can be cases when redirection to the destination fails due to it being blocked by the CORS policy. The best way would be to simply paste the short URL in your browser and see redirection happen.\n2. Make sure the _schemes_ is set to **HTTP** before using the API.\n\n## FAQ\n\n#### How a short key is generated?\n\nIt uses `nanoId` to generate a random string of predefined length.\n\n#### How does it ensure the uniqueness of the key?\n\n- `nanoId` doesn't ensure the uniqueness that's why there is an expiry date set at the time of short URL creation. A short key is open for reuse once the expiry date is hit.\n- There are retries performed if it lands upon a non-expired short key during the random key generation process.\n- Retries are capped and can be tweaked as per the requirement.\n\n#### Does it support Analytics?\n\nIt uses Kafka to send events whenever a short URL is clicked. This gives the flexibility of plugging your own analytics service.\n\n## Contributing\n\nThis project is open for any type of contribution. Feel free to open an issue if you have any query or found a bug.\n\n## License\n\nLicensed under the MIT License, Copyright © 2021\n\nSee [LICENSE](https://github.com/smallcase/smalllinks/blob/development/LICENSE) for more information.\n\n## Used By\n\nThis project is used by the following companies:\n\n- Smallcase Technologies Pvt Ltd\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallcase%2Fsmalllinks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmallcase%2Fsmalllinks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmallcase%2Fsmalllinks/lists"}