From 2d8035f4724f38875d0f29faa1069772d6aadb79 Mon Sep 17 00:00:00 2001
From: "Jakob L. Kreuze" <zerodaysfordays@sdf.org>
Date: Thu, 28 May 2020 19:13:00 -0400
Subject: Document what exists of the API.

---
 README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 56 insertions(+), 6 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 6adbfe0..7ec8b92 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,9 @@ solution such as [Danbooru](https://github.com/danbooru/danbooru).
 
 ## Usage
 
-There are two ways of interacting with бирка-тян: through the `birka`
+### Command-Line
+
+There are two ways of interacting with бирка-тян: through the `birka-cli`
 command-line tool (i), and through the web interface (ii).
 
 The inclusion of (i) is in consideration for this being, essentially, a personal
@@ -29,7 +31,7 @@ integer. The command-line tool operates on these internal identifiers, so it is
 often helpful to obtain the identifier for an image in the filesystem.
 
 ```sh
-$ birka id_for Cat.jpeg
+$ birka-cli id_for Cat.jpeg
 2
 ```
 
@@ -38,29 +40,77 @@ this command is to work. Images are introduced to the database with the `add`
 command, which takes zero or more tags.
 
 ```sh
-$ birka add Cat.jpeg animal cat cute
+$ birka-cli add Cat.jpeg animal cat cute
 ```
 
 Ah, drat. We should have tagged that image with "photograph", too.
 
 ```sh
-$ birka add_tags $(birka id_for Cat.jpeg) photograph
+$ birka-cli add_tags $(birka-cli id_for Cat.jpeg) photograph
 ```
 
 On second thought, that wasn't a particularly cute picture.
 
 ```sh
-$ birka remove_tags $(birka id_for Cat.jpeg) cute
+$ birka-cli remove_tags $(birka-cli id_for Cat.jpeg) cute
 ```
 
 Now, let's see all of the photographs in the tag database tagged with
 "photograph".
 
 ```sh
-$ birka query photograph
+$ birka-cli query photograph
 1,Kww+tPLv/BsbU7M7qqW59ph54v6CSEiUPNpW4XbA0cpoyrrAZsAmT5Ptm30M+hATM71mimoo7PTaS8DEAq57cQ==,/home/jakob/Camera/Cat.jpeg
 ```
 
 The `query` command outputs CSV; the first field is the internal identifier you
 would see from `id_for`, the second is a base64-encoded BLAKE2b hash for the
 image, and the third is the absolute path of the image.
+
+### Web-Interface (API)
+
+The web interface for бирка-тян exposes a RESTful API for remotely interacting
+with the tag database. At the time of writing, this API is __not__ stabilized.
+Expect to rewrite any code depending on this API in the near future, in part
+because these will all be put behind a `/v1/` specifier.
+
+Suppose we denote the following shape of JSON object as a `ImageResult`.
+
+```
+{
+  "id": number,
+  "filename": string,
+  "thumb_filename": string,
+  "tags": [string, ...],
+}
+```
+
+The images in the tag database can be enumerated with the 'posts' endpoint,
+which takes two parameters: `tags`, a comma-separated list of zero or more
+strings, and `last`, which is the last `ImageResult` identifier which was seen.
+This endpoint will return, at most, 50 entries, which is why the `last`
+parameter is necessary.
+
+```
+GET /api/posts?last=number,tags=[string, ...]
+
+[zero or more ImageResult]
+```
+
+Information about a specific image in the database can be obtained with the
+following endpoint, where `id` is the identifier (number) of the image in the
+database:
+
+```
+GET /api/posts/[id]
+
+ImageResult
+```
+
+To upload an image to the database, the blob of data may be POSTED to the
+following endpoint, where `filename` is the desired filename of the image (a
+string):
+
+```
+POST /api/posts/[filename]
+```
-- 
cgit v1.3