From 17f15838088af6228b7fad9d63001c8e82e6c1df Mon Sep 17 00:00:00 2001
From: Pere Lev <pere@towards.vision>
Date: Fri, 5 Jul 2024 21:38:00 +0300
Subject: [PATCH] Document registration API that I'm about to implement

---
 API.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/API.md b/API.md
index e0e8241..16e8ced 100644
--- a/API.md
+++ b/API.md
@@ -89,7 +89,58 @@ curl \
 
 ## Register an Account
 
-There's currently no API endpoint for creating a new account.
+This section isn't implemented yet. I'm about to implement it. Putting the API
+here for review while I'm coding.
+
+### Check if registration is enabled
+
+Send a GET request to the `/register/enabled` endpoint. A 2xx response
+indicates it's enabled, otherwise it's disabled.
+
+### Check username availability
+
+Send a GET request to the `/register/available` endpoint:
+
+```sh
+curl -X GET \
+    -H 'Authorization: Bearer our_application_access_token_here' \
+    -F 'username=alice' \
+    https://vervis.example/register/available
+```
+
+A 2xx response indicates the username is available.
+
+### Create a new account
+
+Send a POST request to the `/register` endpoint:
+
+```sh
+curl -X POST \
+    -H 'Authorization: Bearer our_application_access_token_here' \
+    -F 'username=alice' \
+    -F 'passphrase=R6GQJ9HqLtRQ58' \
+    -F 'email=alice@email.example' \
+    https://vervis.example/register
+```
+
+A 2xx response indicates the account has been created. A JSON object is
+returned, with a boolean `email_sent` field. If true, a verification email has
+been sent to the specified email address. If false, it means email verification
+is disabled on this server, and the account is ready to be used.
+
+### Verify account
+
+The email contains a token, which you can end via a POST request to the
+`/register/verify` endpoint, in order to verify and enable the account:
+
+```sh
+curl -X POST \
+    -H 'Authorization: Bearer our_application_access_token_here' \
+    -F 'token=pRiW8ayeuN7UBW4qAKg9qRBE0DUVCIof' \
+    https://vervis.example/register/verify
+```
+
+A 2xx response indicates successful verification.
 
 ## Log in as Existing User