doc: create README.md

README.md

@@ -0,0 +1,94 @@
+# HREF
+An API-based link redirector/URL shortener using my [Reflect API framework](https://reflect.vlw.se).
+
+Create permalinks to stuff on the internet with an easy-to-use API interface.
+
+## [Example redirection](https://href.vlw.se/demo)
+
+# Installation
+This program requires PHP 8.0+ (with composer) and MariaDB to be installed.
+
+## 1. Clone this repo
+
+Let's start by cloning this repo - preferably to a non-public directory.
+
+```
+git clone https://codeberg.org/vlw/href --depth 1
+```
+
+Point **ALL** requests from your configured webserver to the `public/index.php` file in this repository. Routing is handled by this program.
+
+## 2. Download and import the sample database
+
+[Download the SQL file from the releases page](https://codeberg.org/vlw/href/releases) and import it into an empty MariaDB database.
+
+*Example*
+```sh
+mysql href < href.sql
+```
+
+## 3. Install [Reflect](https://reflect.vlw.se)
+
+Download and install the [Reflect API framework](https://reflect.vlw.se) and follow the installation instructions for that.
+
+Point the reflects `endpoints` environment variable to the root of the directory you cloned before. And the database variable to the database you imported the SQL file into before.
+
+*Example*
+```ini
+# Reflect .env.ini
+endpoints = "/var/www/href"
+# ...
+mysql_db = "href"
+```
+
+## 4. Install dependencies
+Install dependencies for this program with composer
+
+```sh
+composer install --optimize-autoloader
+```
+
+## 5. Create environment variables file
+Copy the `.env.example.ini` file from the root of the repository directory to a file called `.env.ini`.
+
+Set your environment variables in this file.
+
+# Manage permalinks
+
+## Get a permalink
+```
+GET /href?id=<id>
+```
+Make a GET request to the `/href` endpoint passing a permalink `id` as a parameter. The `id` parameter is the same as the database column `id`, and it's also the pathname that you would use when navigating to a permalink.
+
+## Create a permalink
+```
+POST /href
+```
+```json
+# Request body - Content-Type: application/json
+{
+    # This will be the pathname/permalink you wish to redirect from
+    "id":      "example",
+    # This will be the destination URL you wish to redirect to
+    "href":    "https://example.com",
+    # This OPTIONAL parameter can be used to set a comment for the permalink
+    "comment": "An example permalink"
+}
+```
+
+## Update a permalink
+```
+PATCH /href?id=<id>
+```
+A search parameters with the `id` of the permalink you wish to update is required.
+
+This method uses the same request body structure as [`POST`](#create-a-permalink) except all paramers are optional, and parameters present in the request body when the `PATHC` request is sent; will be updated.
+
+## Delete a permalink
+```
+DELETE /href?id=<id>
+```
+A serch paramter with the `id` of the permalink you wish to delete is required.
+
+When a `DELETE` request is made to an `id`, that entry is completely deleted