{"id":22216686,"url":"https://github.com/albertobasalo/api_bun","last_synced_at":"2026-05-04T02:38:31.624Z","repository":{"id":232434363,"uuid":"784354152","full_name":"AlbertoBasalo/api_bun","owner":"AlbertoBasalo","description":"A fast fake API for developers and teachers... made with bun","archived":false,"fork":false,"pushed_at":"2024-04-12T11:59:01.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-12T16:49:45.556Z","etag":null,"topics":["api-rest","bun","developer-tools"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/AlbertoBasalo.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}},"created_at":"2024-04-09T17:25:04.000Z","updated_at":"2024-04-12T16:49:48.685Z","dependencies_parsed_at":"2024-04-12T16:59:50.632Z","dependency_job_id":null,"html_url":"https://github.com/AlbertoBasalo/api_bun","commit_stats":null,"previous_names":["albertobasalo/api_beta","albertobasalo/api_bun"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlbertoBasalo%2Fapi_bun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlbertoBasalo%2Fapi_bun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlbertoBasalo%2Fapi_bun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlbertoBasalo%2Fapi_bun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlbertoBasalo","download_url":"https://codeload.github.com/AlbertoBasalo/api_bun/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245414551,"owners_count":20611367,"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":["api-rest","bun","developer-tools"],"created_at":"2024-12-02T22:12:53.071Z","updated_at":"2026-05-04T02:38:31.591Z","avatar_url":"https://github.com/AlbertoBasalo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🥖 API bun\n\n\u003e [!NOTE]\n\u003e An API server for rapid prototyping, testing, workshops...\n\u003e\n\u003e Delicious JSON fast food ready to consume.\n\u003e\n\u003e This project was cooked using [_bun_](https://bun.sh) v1.1.3.\n\n- 🥖 Just-in-memory or file-based\n- 🥖 Open or secured\n- 🥖 For rapid prototypes\n- 🥖 For front end testing\n- 🥖 For educational purposes\n\n## 1 🍳 Ready for ~~lunch~~ launch\n\n```bash\n# ⬇️ clone the repo\ngit clone https://github.com/AlbertoBasalo/api_bun.git\ncd api_bun\n```\n\n### 1.1 🧑‍🍳 - If you have already _bun_ in your system\n\n```bash\n# 🥖 want to taste this!\nbun run start\n# 🧑‍🍳 To cook in dev mode:\n# install the tools...\nbun i\n# and then run-watching changes.\nbun run dev\n```\n\n### 1.2 🍽️ - If not a _bun_ user, then fallback to npm\n\n\u003e [!TIP]\n\u003e\n\u003e _Bun_ installation is easy and highly recommended.\n\u003e\n\u003e https://bun.sh/docs/cli/install\n\n```bash\n# 🥖 want to taste this!\n# install local bun...\nnpm run bun:i\n# and then start the API server with npm\nnpm start\n```\n\n## 2 🧂 Tasty environment configuration\n\nAPI-bun is configurable through the command line, `.env` file, or code defaults. To get an idea of your flavors, see configuration types and the .env sample below.\n\n```ts\nexport type ApiBunConfig = {\n  /** Log level (info,none,verbose) */\n  LOG_LEVEL: LogLevels;\n  /** Storage type (memory,file) */\n  STORAGE: StorageTypes;\n  /** Security type (none,write) */\n  SECURITY: SecurityTypes;\n  /** Secret */\n  SECRET: string;\n};\n```\n\n\u003e [!TIP]\n\u003e Sample `.env` with default values\n\u003e\n\u003e Create it outside the `src` folder. It will be ignored by git.\n\n```txt\nSTORAGE=memory\nLOG_LEVEL=info\nSECURITY=none\nSECRET=secret\n```\n\n## 3 🥡 Storage\n\n### 3.1 🍱 In Memory\n\nBy default, the API-bun uses an in-memory storage system for rapid prototyping and testing. This means that all data is lost when the server stops. Useful for clean starts.\n\nIf you want to feed the system with some seed data, just create a file named `db/{collection_name}.json` with an array of objects. Api-bun will load it automatically and serve it fresh without touching nothing.\n\nAs any usable example, you can find :\n- a `db/activities.json` file with a list of recreational activities. \n- a `db/categories.json` file with a list of categories for an store.\n- a `db/products.json` file with a list of products for an store.\n\nAlso you can taste flavors of the world by using the amazing [countries-states-cities-database](https://github.com/dr5hn/countries-states-cities-database) files.\n\n### 3.2 🍲 File System\n\nIf you want to persist changes between server restarts, then configure the `.env` file with `STORAGE=file`. This will save all changes to the file system in the `db` folder. Useful for after test analysis or to run in a more realistic scenario.\n\n## 4 🍵 Security\n\n### 4.1 🍩 None\n\nThe default security level is `none`. This means that the API-bun will not require any token to access the resources. Again, this is useful for rapid prototyping and testing, the main goal of this project.\n\n### 4.2 🍪 Signed Token for write\n\nIf you want to add a minimal security layer, then configure the `.env` file with `SECURITY=write`. This will require a signed token to access the resources. The token is generated with the `SECRET` value in the `.env` file.\n\nWhen enabled, any `POST, PUT, PATCH or DELETE` request to the API must include the token in the `Authorization` header with the `Bearer` prefix.\n\nThe identified user `id` is also added to any posted item as `userId` property as an owner for future fine grained security.\n\n\u003e [!CAUTION]\n\u003e The token is not JWT compliant and is only a minimal security layer.\n\n#### To register a new user\n\n```bash\ncurl -X POST http://localhost:3000/api/register -d '{\"email\":\"admin@world.org\",\"password\":\"1234\"}' -H \"Content-Type: application/json\"\n```\n\n#### To login\n\n```bash\ncurl -X POST http://localhost:3000/api/login -d '{\"email\":\"admin@world.org\",\"password\":\"1234\"}' -H \"Content-Type: application/json\"\n```\n\n## 5 🍕 API endpoints\n\n### 5.1 🍟 Get data\n\n```bash\n# get all activities\nhttp://localhost:3000/api/activities\n# get one activity\nhttp://localhost:3000/api/activities/1\n# get activities by key/value\nhttp://localhost:3000/api/activities?key=slug\u0026value=standup-surfing_laco-di-como_2023-08-01\n# get by content\nhttp://localhost:3000/api/activities?q=surf\n```\n\n## 6 🍔 Forced responses\n\nWhen testing your app, sometimes you want to force the API to return a specific response. This can be done by adding some query parameter to the request.\n\n### 6.1 🍟 Forced status codes\n\nTo force a specific status code, add the `status` query parameter to the request.\n\n```bash\ncurl -X GET http://localhost:3000/api/activities?status=404\n```\n\n### 6.2 🍕 Forced delay\n\nTo force a delay in the response, add the `delay` query parameter to the request. The value is in milliseconds.\n\n```bash\ncurl -X GET http://localhost:3000/api/activities?delay=5000\n```\n\n## X 🥪 Hot features and cold road-map\n\n- [x] Publishes a generic CRUD API\n- [x] Endpoint routes in the form `http://localhost:3000/api/{collection_name}` for GET all or POST.\n- [x] Add the _id_ `http://localhost:3000/api/{collection_name}/{id}` for GET one, PUT or DELETE.\n- [x] Add _queryParams_ `http://localhost:3000/api/{collection_name}?key={key}\u0026value={value}` for GET by key/value.\n- [x] Always try to feeds any resource with seed data from `db/{collection_name}.json`.\n- [x] If no file found, then starts with an empty array.\n- [x] Uses _id_ as a primary key to identify items.\n- [x] If not supplied during POST, then generates a new random _id_.\n- [x] Configuration with `.env` file or command line (see below).\n- [x] If configured with `STORAGE=file`, then persist changes (POST,PUT, DELETE) to file system.\n- [x] PUT works like a PATCH, only updating the fields supplied.\n- [x] Logs to console with different levels (_info, none, verbose_).\n- [x] Minimal security with signed token (not JWT compliant).\n- [ ] _JWT Security and authorization_\n- [ ] _Clear an endpoint when DELETE to the endpoint root_\n- [ ] _Sorted results_\n- [ ] _Pagination_\n- [ ] _Put and patch distinction_\n- [ ] _Allow to configure the root api route_\n- [ ] _Allow to configure the primary key property name_\n- [ ] _Allow to configure the storage path_\n- [ ] _Published to npm_\n\n---\n\n\u003e [!CAUTION]\n\u003e Not suitable for production use. Use only for rapid prototyping, testing, workshops...\n\n---\n\n\u003cfooter\u003e\n  \u003ch3\u003e🧑🏼‍💻 By \u003ca href=\"https://albertobasalo.dev\" target=\"blank\"\u003eAlberto Basalo\u003c/a\u003e \u003c/h3\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://twitter.com/albertobasalo\" target=\"blank\"\u003e\n      \u003cimg src=\"https://img.shields.io/twitter/follow/albertobasalo?logo=twitter\u0026style=for-the-badge\" alt=\"twitter albertobasalo\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://github.com/albertobasalo\" target=\"blank\"\u003e\n      \u003cimg \n        src=\"https://img.shields.io/github/followers/albertobasalo?logo=github\u0026label=profile albertobasalo\u0026style=for-the-badge\" alt=\"git albertobasalo\" /\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/footer\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertobasalo%2Fapi_bun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbertobasalo%2Fapi_bun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertobasalo%2Fapi_bun/lists"}