kvrest
kvrest copied to clipboard
Split174
Simple kv storage with rest-api, on top of embedded bbolt db
Key-Value Store API with Telegram Bot Integration
This project provides a key-value storage API using Go and bbolt to store the database. Users can create their own key-value store via Telegram. With the ability to easily transfer storage to your server.
Table of Contents
- Why?
- Cloud usage
- Telegram Bot Commands
- API Endpoints
- Migrate on your server
- Project Structure
- Requirements
- Dependencies
Why?
Because I can. I'm tired of mongo/postgresql/etc support for my small projects. Endless choice of providers, headache with migration to your servers, etc. (I also wanted to practice golang)
Make coding fun again.
Cloud usage
- Start telegram bot - https://t.me/kvrest_bot
- Send /start in bot
Telegram Bot Commands
/help
Displays the documentation for all available commands to the user.
/start
Creates a new key-value (KV) store for the user. It generates a unique API key and creates a new BoltDB file to store the user's data. The API key is then sent back to the user.
/change_api_key
Allows the user to change their existing API key. It generates a new API key, renames the BoltDB file with the new key, and sends the new API key to the user.
/view_bucket_keys
Allows the user to view the keys stored in a specific bucket within their KV store. The user needs to provide the name of the bucket they want to view.
Usage: /view_bucket BUCKET_NAME
/list_buckets
Lists all the buckets that the user has created in their KV store.
/download_kv
Allows the user to download their entire KV store as a BoltDB file. The bot will send the file directly to the user.
API Endpoints
Creating a new bucket
PUT /{bucketName}
Parameters
name type data type description bucketNamerequired string Name of the bucket to create
Responses
http code content-type response 200text/plain;charset=UTF-8Bucket created successfully405text/plain;charset=UTF-8Bucket name 'system' not allowed500text/plain;charset=UTF-8Internal Server Error
Example cURL
curl -X PUT -H "API-KEY: your_api_key" https://kvrest.dev/api/yourBucketName
Deleting an existing bucket
DELETE /{bucketName}
Parameters
name type data type description bucketNamerequired string Name of the bucket to delete
Responses
http code content-type response 200text/plain;charset=UTF-8Bucket deleted successfully500text/plain;charset=UTF-8Internal Server Error
Example cURL
curl -X DELETE -H "API-KEY: your_api_key" https://kvrest.dev/api/yourBucketName
Listing all buckets
POST /buckets
Responses
http code content-type response 200application/json{"buckets": ["example-buckets1", "example-buckets2"]}500text/plain;charset=UTF-8Internal Server Error
Example cURL
curl -X POST -H "API-KEY: your_api_key" https://kvrest.dev/api/buckets
Creating/updating a key-value pair in a bucket
PUT /{bucketName}/{key}
Parameters
name type data type description bucketNamerequired string Name of the bucket keyrequired string Name of the key within the bucket None (body) required object (JSON) Value to be set for the key
Responses
http code content-type response 200text/plain;charset=UTF-8None 400text/plain;charset=UTF-8Bad Request500text/plain;charset=UTF-8Internal Server Error
Example cURL
curl -X PUT -H "API-KEY: your_api_key" -H "Content-Type: application/json" --data '{"key": "value"}' https://kvrest.dev/api/yourBucketName/yourKey
Retrieving a value for a key in a bucket
GET /{bucketName}/{key}
Parameters
name type data type description bucketNamerequired string Name of the bucket keyrequired string Name of the key within the bucket
Responses
http code content-type response 200application/jsonJSON object representing the value 404text/plain;charset=UTF-8Key not found500text/plain;charset=UTF-8Internal Server Error
Example cURL
curl -X GET -H "API-KEY: your_api_key" https://kvrest.dev/api/yourBucketName/yourKey
Deleting a key-value pair in a bucket
DELETE /{bucketName}/{key}
Parameters
name type data type description bucketNamerequired string Name of the bucket keyrequired string Name of the key within the bucket
Responses
http code content-type response 200text/plain;charset=UTF-8None 500text/plain;charset=UTF-8Internal Server Error
Example cURL
curl -X DELETE -H "API-KEY: your_api_key" https://kvrest.dev/api/yourBucketName/yourKey
Listing all keys in a bucket
GET /{bucketName}
Parameters
name type data type description bucketNamerequired string Name of the bucket to list keys from
Responses
http code content-type response 200application/json{"keys": ["example-key1", "example-key2"]}404text/plain;charset=UTF-8Bucket not found500text/plain;charset=UTF-8Internal Server Error
Example cURL
curl -X GET -H "API-KEY: your_api_key" https://kvrest.dev/api/yourBucketName
Migrate on your server
Download db file from bot /download_db.
mkdir -p ./kvrest && cp /file/from-bot/file.db ./kvrest/ cd ./kvrest/ docker run --rm -it -p 8080:8080 -v ${PWD}:/app/data ghcr.io/split174/kvrest:v1.0.1
Test:
curl -X POST -H "API-KEY: DB-FILE-FROM-BOT" http://localhost:8080/api/buckets
Project Structure
├── api
│ ├── api.go
│ └── api_test.go
├── Caddyfile
├── docker-compose.yml
├── Dockerfile
├── go.mod
├── go.sum
├── main.go
├── README.md
└── telegram_bot
└── telegram_bot.go
Requirements
- Go 1.16 or later
- A valid Telegram Bot Token
Dependencies
This project uses the following Go packages:
Split174