From ad00b553d845dba8af7b0e9fa2930209aee1dd62 Mon Sep 17 00:00:00 2001
From: Owen Jacobson <owen@grimoire.ca>
Date: Sat, 19 Oct 2024 00:57:20 -0400
Subject: Make the responses for various data creation requests more
 consistent.

In general:

* If the client can only assume the response is immediately valid (mostly, login creation, where the client cannot monitor the event stream), then 200 Okay, with data describing the server's view of the request.

* If the client can monitor for completion by watching the event stream, then 202 Accepted, with data describing the server's view of the request.

This comes on the heels of a comment I made on Discord:

> hrm
>
> creating a login: 204 No Content, no body
> sending a message: 202 Accepted, no body
> creating a channel: 200 Okay, has a body
>
> past me, what were you on

There wasn't any principled reason for this inconsistency; it happened as the endpoints were written at different times and with different states of mind.
---
 docs/api/authentication.md | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

(limited to 'docs/api/authentication.md')

diff --git a/docs/api/authentication.md b/docs/api/authentication.md
index d4c1f70..7e05443 100644
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -56,7 +56,21 @@ The request must have the following fields:
 
 <!-- This prose is duplicated by 03-initial-setup.md and in 04-invitations.md, with small changes for context. If you edit it here, edit it there, too. -->
 
-This endpoint will respond with a status of `204 No Content` when successful.
+This endpoint will respond with a status of `200 Okay` when successful. The body of the response will be a JSON object describing the authenticated login:
+
+```json
+{
+	"id": "Labcd1234",
+	"name": "Andrea"
+}
+```
+
+The response will include the following fields:
+
+| Field       | Type   | Description |
+|:------------|:-------|:--|
+| `id`        | string | The authenticated login's ID. |
+| `name`      | string | The authenticated login's name. |
 
 The response will include a `Set-Cookie` header for the `identity` cookie, providing the client with a newly-minted identity token associated with the login identified in the request. This token's value must be kept confidential.
 
-- 
cgit v1.2.3