chore: update README with API endpoint docs

README.md

@@ -1,30 +1,156 @@
-TBC
-
-| HTTP Method | Path            | Parameter     | Returns                          |
-| ----------- | --------------- | ------------- | -------------------------------- |
-| GET         | `entry`         | `entry_title` | Body text, tags, title           |
-| GET         | `tag`           | `tag_name`    | List of entries for supplied tag |
-| GET         | `refs`          | `entry_title` | List of linked entries           |
-| GET         | `full_metadata` | `entry_title` | Tags, links, last modified       |
-| GET         | `graph`         | `null`        | Full network graph               |
-
 ## Deployment
 
 Deployment is automated via Forgejo action (see `.forgejo/workflows/deploy.yml`).
 
+Deployment actions are always executed by the `deploy` user on the VPS.
+
 On pushes to `main`:
 
-- Automatically bump version in accordance with Semver:
+- Automate versioning and Git tagging:
 
-  - Major: `major: <commit description>`,
+  - Commit keyword corresponds to SemVer:
-  - Minor: `feat: <commit description>`,
+    - Major: `major: <commit description>`,
-  - Patch: `fix: <commit description>`
+    - Minor: `feat: <commit description>`,
-  - Ignored keywords: `chore`, `test`, `refactor`, and anything else
+    - Patch: `fix: <commit description>`
+    - Ignored keywords: `chore`, `test`, `refactor`, and anything else
+  - This updates the version in `package.json` and creates Git tag at this version.
 
-- This bumps the version in `package.json` and creates Git tag at this version.
+- Install `rsync` on the `ubuntu-latest` runner, then:
 
-- SSH to VPS using `deploy` user and :
+  - Rsync over SSH to copy changed files from this repository to VPS deployment directory, excluding
+    `.env`
 
-  - Purge existing source files at `var/www/eolas-api`,
+- Restart eolas-api using `systemd`
-  - Copy over new source files
+
-  - TODO: restart Node server
+## API
+
+### Entries
+
+#### Get all entries
+
+Return all entries. Optionally limit by length and/or date.
+
+```
+GET /entries?limit=2&sort=date
+```
+
+```json
+{
+  "count": 5,
+  "data": [
+    {
+      "title": "SSH",
+      "last_modified": "2025-07-10 14:26:04"
+    },
+    {
+      "title": "List_largest_files_bash",
+      "last_modified": "2025-07-07 16:49:12"
+    }
+  ]
+}
+```
+
+#### Get specific entry
+
+```
+GET /entries/Memory_versus_processor
+```
+
+```json
+{
+  "title": "Memory_versus_processor",
+  "last_modified": "2024-10-18 19:17:01",
+  "size": 270,
+  "body": "# Memory versus processor\n\n Would a more powerful processor with average or reduced memory capacity..."
+}
+```
+
+#### Get backlinks for an entry
+
+Defaults to alphabetic list.
+
+```
+GET /entries/backlinks/The_kernel
+```
+
+```json
+{
+  "count": 3,
+  "data": ["Boot_process", "Containerization", "CPU_architecture"]
+}
+```
+
+#### Get outlinks for an entry
+
+Defaults to alphabetic list.
+
+```
+GET /entries/outlinks/The_kernel
+```
+
+```json
+{
+  "count": 3,
+  "data": ["Basic_model_of_the_operating_system", "Processes", "User_Space"]
+}
+```
+
+#### Get entries associated with a specified tag
+
+Optionally sort chronologically.
+
+```
+GET /entries/tag/memory?sort=date
+```
+
+```json
+{
+  "count": 3,
+  "data": [
+    {
+      "entry_title": "Memory_addresses"
+    },
+    {
+      "entry_title": "Call_stack"
+    },
+    {
+      "entry_title": "The_memory_hierarchy"
+    }
+  ]
+}
+```
+
+### Tags
+
+#### Get all tags
+
+Sorted alphabetically.
+
+```
+GET /tags
+```
+
+```json
+{
+  "count": 119,
+  "data": ["algebra", "algorithms", "analogue", "android", "..."]
+}
+```
+
+#### Get tags for specified entry
+
+```
+GET /tags/The_kernel
+```
+
+```json
+{
+  "count": 4,
+  "data": [
+    "computer-architecture",
+    "memory",
+    "operating-systems",
+    "systems-programming"
+  ]
+}
+```