From 4bba5955bf0427fc2540bde5b6d4dd12cef21b15 Mon Sep 17 00:00:00 2001 From: K0IN Date: Mon, 24 Jul 2023 23:55:23 +0200 Subject: [PATCH] Update documentation --- doc/api.md | 171 ++++++++++++++++++++++++++------------------- doc/baremetal.md | 0 doc/deploy.md | 0 doc/development.md | 9 --- doc/frontend.md | 7 -- doc/install.md | 15 ++-- doc/wrangler.md | 37 ---------- readme.md | 17 +++++ 8 files changed, 127 insertions(+), 129 deletions(-) create mode 100644 doc/baremetal.md create mode 100644 doc/deploy.md delete mode 100644 doc/development.md delete mode 100644 doc/frontend.md delete mode 100644 doc/wrangler.md diff --git a/doc/api.md b/doc/api.md index 6d6e40a2..0d14d8a7 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1,142 +1,169 @@ -# API DOC +# API Documentation ## Routes All routes are prefixed with `/api` -## keys endpoint +--- -### get vapid keys +## Notifications Endpoint -**URL** : `/api/keys` +### Send a Notification to All Devices -**Method** : `GET` +**URL**: `/api/notify` -**Auth required** : No +**Method**: `POST` -**Description** : get the server vapid key to create a client subscription +**Auth required**: Yes (only if the server password is set). Authentication +header must be `Bearer `. -#### Success Responses +**Description**: Send a notification to all devices. -**Code** : `200 OK` - -**Content** : +**Body**: ```json -{"successful":true,"data":"BGDRJjAeUMkFC1uFnqR0L5-VlqwV6RxhQedXid6CY95ONU3NCQI82-WvNWc2vc9HV8YOIAC9VsMrMhJhi3XS8MQ"} +{ + "title": "", + "message": "<message>", + "icon": "<optional icon url>", + "tags": ["<optional list of strings>"] +} ``` -## device endpoint - -### create a new device - -**URL** : `/api/device` +#### Success Response -**Method** : `POST` +**Code**: `200 OK` -**Auth required** : no (only if the serverpassword is set) Authentication header must be `Bearer <serverpassword>` - -**Description** : create a new device and return the device id with a secret that can be used to delete it later - -**Body** : +**Content**: ```json { - "web_push_data":{ - "endpoint":"<endpoint url>", - "key":"<base64 encoded subscription p256 key>", - "auth":"<base64 encoded subscription auth>" - } + "successful": true, + "data": "notified" } ``` -#### Success Responses +--- -**Code** : `200 OK` +## Keys Endpoint -**Content** : +### Get Vapid Keys -```json -{"successful":true,"data":{"id":"c968712190ec72e785160fe2a45b45a4","secret":"bd907b2a5f9e571949aa92561fcb5694"}} -``` +**URL**: `/api/keys` -### Check if a device exists +**Method**: `GET` -**URL** : `/api/device/<device_id>` +**Auth required**: No -**Method** : `GET` +**Description**: Get the server Vapid key to create a client subscription. -**Auth required** : No +#### Success Response -**Description** : check if a device exists +**Code**: `200 OK` -#### Success Responses - -**Code** : `200 OK` - -**Content** : +**Content**: ```json -{"successful":true,"data":true} +{ + "successful": true, + "data": "BGDRJjAeUMkFC1uFnqR0L5-VlqwV6RxhQedXid6CY95ONU3NCQI82-WvNWc2vc9HV8YOIAC9VsMrMhJhi3XS8MQ" +} ``` -### Delete a device +--- -**URL** : `/api/device/<device_id>` +## Device Endpoint -**Method** : `DELETE` +### Create a New Device -**Auth required** : No +**URL**: `/api/device` -**Description** : delete a device +**Method**: `POST` -**Body** : +**Auth required**: No (only if the server password is set). Authentication header must be `Bearer <serverpassword>`. + +**Description**: Create a new device and return the device ID with a secret that +can be used to delete or update it later. + +**Body**: ```json { - "secret":"<device secret>" + "web_push_data": { + "endpoint": "<endpoint url>", + "key": "<base64 encoded subscription p256 key>", + "auth": "<base64 encoded subscription auth>" + } } ``` -#### Success Responses +#### Success Response -**Code** : `200 OK` +**Code**: `200 OK` -**Content** : +**Content**: ```json -{"successful":true,"data":"device deleted"} +{ + "successful": true, + "data": { + "id": "c968712190ec72e785160fe2a45b45a4", + "secret": "bd907b2a5f9e571949aa92561fcb5694" + } +} ``` -## Notifications endpoint +### Check If a Device Exists -### Send a notification to all devices +**URL**: `/api/device/<device_id>` -**URL** : `/api/notify` +**Method**: `GET` -**Method** : `POST` +**Auth required**: No -**Auth required** : yes (only if the serverpassword is set) Authentication header must be `Bearer <serverpassword>` +**Description**: Check if a device exists. -**Description** : send a notification to all devices +#### Success Response -**Body** : +**Code**: `200 OK` + +**Content**: + +```json +{ + "successful": true, + "data": true +} +``` + +### Delete a Device + +**URL**: `/api/device/<device_id>` + +**Method**: `DELETE` + +**Auth required**: No + +**Description**: Delete a device. + +**Body**: ```json { - "title":"<title>", - "message":"<message>", - "icon":"<optional icon url>", - "tags": [<optional list of strings>] + "secret": "<device secret>" } ``` -#### Success Responses +#### Success Response -**Code** : `200 OK` +**Code**: `200 OK` -**Content** : +**Content**: ```json -{"successful":true,"data":"notified"} -``` \ No newline at end of file +{ + "successful": true, + "data": "device deleted" +} +``` + diff --git a/doc/baremetal.md b/doc/baremetal.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/deploy.md b/doc/deploy.md new file mode 100644 index 00000000..e69de29b diff --git a/doc/development.md b/doc/development.md deleted file mode 100644 index f573ee66..00000000 --- a/doc/development.md +++ /dev/null @@ -1,9 +0,0 @@ -# Development - -## Environment - -For easy development we provide a approved devcontainer with preinstalled chrome, to run all the test locally (puppeteer can be a pain sometimes). - -## Code - -> todo diff --git a/doc/frontend.md b/doc/frontend.md deleted file mode 100644 index 38ba410c..00000000 --- a/doc/frontend.md +++ /dev/null @@ -1,7 +0,0 @@ -# Frontend doc - -## Config - -you can run the frontend separately from the backend (domain or port). -you will need to adjust the api path in [the frontend settings file](../app/frontend/src/staticsettings.js) before you build the project. -make sure you enable the cors header inside the env or [wrangler](/app/wrangler.toml) file. diff --git a/doc/install.md b/doc/install.md index ae2d7276..86184f4e 100644 --- a/doc/install.md +++ b/doc/install.md @@ -1,6 +1,13 @@ # User's Guide: Installation -## Deploying to deno deploy 🚀 +## Api Documentation 📚 + +The API is very simple and easy to use. +You can find the documentation [here](api.md). + +## Deployment Options 🚀 + +### Deploying to deno deploy 🚀 If you don't want to host it yourself, you can deploy it to deno deploy. Deno deploy enables easy and efficient deployment of application. @@ -8,14 +15,14 @@ It is also free (as of now) and requires no credit card to get started. [Learn more](install/deploy.md) -## Containerization with Docker 🐳 +### Containerization with Docker 🐳 If you prefer containerization for your applications, Docker is the way to go. Docker is a fast way to deploy the application on your own infrastructure. -[Learn more](install/selfhosted.md) +[Learn more](install/docker.md) -## Running on Bare Metal 💻 +### Running on Bare Metal 💻 If you prefer to run the project on bare metal, you can do so as well. diff --git a/doc/wrangler.md b/doc/wrangler.md deleted file mode 100644 index 4822ab65..00000000 --- a/doc/wrangler.md +++ /dev/null @@ -1,37 +0,0 @@ -# Wrangler - -## Secrets - -### VAPID_SERVER_KEY - -This key is used to sign the web push messages, so it is important to keep it secret. -Generate it with [helper/browser.js](../helper/browser.js) or [helper/deno.ts](../helper/deno.ts) file. -Also if you get stuck please refer to the [install guide](./install.md) for help. - -### SERVERPWD - -This is the password for the (send push) webhook endpoint you will need to set your Authentication header to `bearer <SERVERPWD>` - -default: "" (empty) -> no password set - -### AUTHPWD - -This is the password that will be used to authenticate the user inside the web interface. - -default: "" (empty) -> no password set - -## Env Variables - -### SUB - -this will be send to the push service. The 'subscriber'is the primary contact email for this subscription. - -### CORS_ORIGIN - -adds a cors header to the response so you can run the frontend on a different domain - -(note: the webhook endpoint has always cors origin *) - -### SERVE_FRONTEND - -set to true if the frontend should be served else set it to empty string to disable it diff --git a/readme.md b/readme.md index 1065836f..cfba6402 100644 --- a/readme.md +++ b/readme.md @@ -30,6 +30,23 @@ curl -X POST -H "Content-Type: application/json" -d '{"title":"Hello", "message" Don't worry about complicated setups. The installation documentation is right here to help you get started with Notify in no time! 📚 👉 [Installation Documentation](doc/install.md) +👉 [Api Documentation](doc/api.md) + +## Features 🎉 + +- Send push messages to any device that supports web push +- Easy installation with Docker, bare metal, or Deno Deploy +- Offline installable PWA +- Customize your notifications with optional features like adding an icon +- Open-source and free to use +- No registration required +- Easy to use API + +## Need Help? 🤔 + +- Refer to our great [documentation](doc/install.md) +- Start a discussion on [GitHub Discussions](https://github.com/K0IN/Notify/discussions) +- Open an [new issue](https://github.com/K0IN/Notify/issues/new) ## Ready to Get Notified? 🚀