{"id":16368587,"url":"https://github.com/puzpuzpuz/zeptourl-api","last_synced_at":"2025-06-14T16:38:27.127Z","repository":{"id":128963330,"uuid":"158186134","full_name":"puzpuzpuz/zeptourl-api","owner":"puzpuzpuz","description":"A TinyURL-like demo application","archived":false,"fork":false,"pushed_at":"2018-12-03T10:52:44.000Z","size":183,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-15T00:48:51.163Z","etag":null,"topics":["cassandra","node","tinyurl"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/puzpuzpuz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-19T08:22:15.000Z","updated_at":"2019-06-07T14:04:32.000Z","dependencies_parsed_at":"2023-04-04T19:00:17.351Z","dependency_job_id":null,"html_url":"https://github.com/puzpuzpuz/zeptourl-api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/puzpuzpuz/zeptourl-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzpuzpuz%2Fzeptourl-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzpuzpuz%2Fzeptourl-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzpuzpuz%2Fzeptourl-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzpuzpuz%2Fzeptourl-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/puzpuzpuz","download_url":"https://codeload.github.com/puzpuzpuz/zeptourl-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/puzpuzpuz%2Fzeptourl-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259847453,"owners_count":22921130,"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":["cassandra","node","tinyurl"],"created_at":"2024-10-11T02:53:12.565Z","updated_at":"2025-06-14T16:38:27.107Z","avatar_url":"https://github.com/puzpuzpuz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zeptourl-api\n\nA lightweight TinyURL-like demo application, a RESTful web service. Built with Node.js and Cassandra.\n\n## Overview\n\nThe main problem with TinyURL-like application is scaling. This app solves the problem in one of the most simple, yet good enough manners.\n\nEach time when a new URL minification request is received, the app generates a random URL (let's call it zURL) which is a Base32-encoded string of a constant length (specified in the config). Then it tries to insert a new record into Cassandra. The insert fails in case of a possible collision (thanks to the [`IF NOT EXISTS` clause](https://docs.datastax.com/en/cql/3.3/cql/cql_reference/cqlInsert.html)). This process repeats several times (also specified in the config).\n\nWhile this design assumes that collisions will be happening more and more frequently while the DB grows, it may be enhanced in a quite simple way. Number of collisions per zURL generation request may be somehow monitored externally, e.g. via logging and ELK-stack. Once it reaches a certain threshold, say two collisions per 5th percentile of requests, new Node.js instances with an increased value of the length parameter may be deployed.\n\n## Requirements\n\nThe app assumes using Node.js 10 and Cassandra 3. You can use Docker and Docker Compose for dev environment as well.\n\n## Dev Environment\n\nTo start all application components run the following command:\n\n```bash\ndocker-compose up\n```\n\nThis command will start a Cassandra cluster of two nodes and the app itself, so it may take a while (at least 60s). Also make sure that you have at least 2GB of memory available for Docker.\n\nOnce started the API will be available on [http://localhost:3000/api/v1](http://localhost:3000/api/v1).\n\nTo start the Node.js application only run the following commands:\n\n```bash\nnpm ci\nnpm run start\n```\n\nIn this case, you might need to change DB connection settings (see `app/config/development.json` config).\n\n## Configuration\n\nCurrent configuration type is specified by `NODE_ENV` environment variable. Default configuration type is `development`. Parameters for each type are stored in `app/config/` directory.\n\nThe app is using [nconf](https://github.com/indexzero/nconf) internally to manage the configuration. So any config parameter can be overridden via environment variables. For instance, `app.zUrlGenRetries` parameter can be overridden by an env var with `app:zUrlGenRetries`.\n\n## API Specification\n\nAPI specification is described in `api-spec.yml` file (in Open API v3.0 format). Once dev environment is started by docker-compose, Swagger UI becomes available on [http://localhost:8080/](http://localhost:8080/).\n\n## License\n\nCopyright 2018 puzpuzpuz\n\nLicensed under MIT.\n\n## Possible enhancements\n\n* Implement sufficient amount of unit tests (there are a few tests at the moment)\n* Integrate [loopbench](https://github.com/mcollina/loopbench) into system-info#metrics\n* Try using a more lightweight logger (see [pino](https://github.com/pinojs/pino))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuzpuzpuz%2Fzeptourl-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpuzpuzpuz%2Fzeptourl-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpuzpuzpuz%2Fzeptourl-api/lists"}