diff options
| author | Owen Jacobson <owen@grimoire.ca> | 2024-10-19 00:57:20 -0400 |
|---|---|---|
| committer | Owen Jacobson <owen@grimoire.ca> | 2024-10-19 00:57:20 -0400 |
| commit | ad00b553d845dba8af7b0e9fa2930209aee1dd62 (patch) | |
| tree | 0a91c3c0113b2618730d3160f311c083e95b0581 /docs/api/initial-setup.md | |
| parent | 635d92eb4ffc5a1c94cba784a2a4f18e1cb5effc (diff) | |
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.
Diffstat (limited to 'docs/api/initial-setup.md')
| -rw-r--r-- | docs/api/initial-setup.md | 16 |
1 files changed, 15 insertions, 1 deletions
diff --git a/docs/api/initial-setup.md b/docs/api/initial-setup.md index ad57089..3c5a8a6 100644 --- a/docs/api/initial-setup.md +++ b/docs/api/initial-setup.md @@ -55,7 +55,21 @@ The request must have the following fields: <!-- This prose is duplicated from authentication.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 newly-created login: + +```json +{ + "id": "Labcd1234", + "name": "Andrea" +} +``` + +The response will include the following fields: + +| Field | Type | Description | +|:------------|:-------|:--| +| `id` | string | A unique identifier for the newly-created login. This can be used to associate the login with other events, or to make API calls targeting the login. | +| `name` | string | The 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 initial login created for this request. See the [authentication](./authentication) section for details on how this cookie may be used. |