{"id":15413366,"url":"https://github.com/simonwep/genesis","last_synced_at":"2025-12-29T18:29:06.188Z","repository":{"id":176690412,"uuid":"651627847","full_name":"simonwep/genesis","owner":"simonwep","description":"🧞 A simple, generic, fast and lightweight json api for frontend apps. Store your frontend-data as-is without messing around with a database!","archived":false,"fork":false,"pushed_at":"2025-03-28T16:49:42.000Z","size":110,"stargazers_count":5,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T17:44:50.793Z","etag":null,"topics":["api","backend-api","backend-service","golang","json"],"latest_commit_sha":null,"homepage":"","language":"Go","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/simonwep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-06-09T17:06:43.000Z","updated_at":"2025-03-28T16:46:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"d7d3d90a-963d-4d04-b81b-fe6925ae4aef","html_url":"https://github.com/simonwep/genesis","commit_stats":{"total_commits":71,"total_committers":1,"mean_commits":71.0,"dds":0.0,"last_synced_commit":"9d1ab459646fbc2942dd2fd08bf0153e8bfce55b"},"previous_names":["simonwep/genisis"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fgenesis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fgenesis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fgenesis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonwep%2Fgenesis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonwep","download_url":"https://codeload.github.com/simonwep/genesis/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249685230,"owners_count":21310568,"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","backend-api","backend-service","golang","json"],"created_at":"2024-10-01T16:56:47.010Z","updated_at":"2025-12-29T18:29:06.141Z","avatar_url":"https://github.com/simonwep.png","language":"Go","readme":"\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003eGenesis\u003c/h3\u003e\n  \u003ch4\u003eA generic JSON api for small, private frontend apps\u003c/h4\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/simonwep/genesis\"\u003e\n    \u003cimg src=\"https://goreportcard.com/badge/github.com/simonwep/genesis\" alt=\"Go Report Card\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/simonwep/genesis/actions/workflows/main.yml\"\u003e\n    \u003cimg src=\"https://github.com/simonwep/genesis/actions/workflows/main.yml/badge.svg\" alt=\"CI Status\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n### Summary\n\nThis project is designed specifically for small, personal projects requiring a straightforward, simple storage API that you can host yourself, including simplified user management.\n\n### Usage\n\nFirst, create a [.env](.env.example) and specify the initial usernames and passwords for access.\nMake sure to fill out `GENESIS_JWT_SECRET` with a secure, random string, for that you can use `openssl rand -hex 32`.\nYou can specify the remaining values, but the defaults are good for medium-sized projects such as [ocular](https://github.com/Simonwep/ocular).\n\nSecond, start the server via `go run . start` - That's it.\nHead to the [api](#api) documentation to see how to use it.\nUse `go run . help` to see all available commands.\n\nThe `json` is pre-processed by the [minify](https://github.com/tdewolff/minify) package to minimize and validate it.\n\n#### Using docker\n\nYou can run genesis using [docker](https://www.docker.com/products/docker-desktop/) by using pre-build images:\n\n```sh\ndocker run -p 8080:8080 -v \"$(pwd)/.data:/app/.data\" --env-file .env ghcr.io/simonwep/genesis:latest start\n```\n\nGenesis should then be accessible under port `8080`.\n\n\u003e [!NOTE]\n\u003e You can specify the base-url via the env variable `GENESIS_BASE_URL`.\n\n### CLI\n\nGenesis comes with a CLI to manage users.\nYou can access it by running `go run . users help` or via docker using the following command:\n\n```sh\ndocker run --rm -v \"$(pwd)/.data:/app/.data\" --env-file .env ghcr.io/simonwep/genesis:latest help\n```\n\n### API\n\nThe API is kept as simple as possible; there is nothing more than user, data, and account management.\n\n#### Authentication and account\n\n* `POST /login` - Authenticates a user.\n  - Takes either a `user` and `password` as JSON object and returns the user-data and a session cookie or, if a session-cookie exists, the current user.\n  - Returns `401` the password is invalid or the user doesn't exist.\n* `POST /logout` - Invalidates the current refresh token and logs out a user.\n* `POST /account/update`\n  - Takes a `newPassword` and `currentPassword` as JSON object.\n  - Returns `200` if the password was successfully updated, otherwise `400`.\n\n\u003e [!NOTE]\n\u003e The JWT token is returned as a strict same-site, secure and http-only cookie!  \n\u003e When changing the password, the new password must fulfill the same requirements for adding a new user.\n\n#### Data endpoints\n\n* `GET /data` - Retrieves all data from the current user as object.\n* `GET /data/:key` - Retrieves the data stored for the given `key`. Returns `204` if there is no content.\n* `POST /data/:key` - Stores / overrides the data for `key`.\n* `DELETE /data/:key` - Removes the data for `key`, always returns `200`, even if `key` doesn't exist.\n\n\u003e [!NOTE]\n\u003e Validation parameters for those endpoints are defined in [.env](.env.example).  \n\u003e This includes a key-pattern, the max amount per user, and a size-limit.\n\n#### User management\n\n\u003e Admins can only use these endpoints!\n\n* `GET /user` - Fetch all users as `{ name: string, admin: boolean }[]`.\n* `POST /user` - Create a user, takes a JSON object with `user`, `password` and `admin` (all mandatory, `admin` is a boolean).\n* `POST /user/:name` - Update a user by `name`, takes a JSON object with `password` and `admin` (both optional).\n* `DELETE /user/:name` - Delete a user by `name`.\n\n\u003e [!NOTE]\n\u003e The username is validated against the pattern defined in [.env](.env.example).  \n\u003e The length must be between `3` and `32`, the password between `8` and `64`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonwep%2Fgenesis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonwep%2Fgenesis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonwep%2Fgenesis/lists"}