Fix some typos

2025-06-18 22:49:21 +10:00
parent f7a08ff3ab
commit 536ac10fec

@@ -1,10 +1,10 @@
# Dreamspace API Usage Overviee # Dreamspace API Usage Overview
## Getting Started ## Getting Started
### The API Format ### The API Format
This APIsupports CRUD (Create, Read, Update, and Delete) operations for the objects and models of 'Dreamspace Adventures'. (See [[index#Models]] for a brief list of manipulatable modules, or the below API Reference for more comprehensive detail.) This API supports CRUD (Create, Read, Update, and Delete) operations for the objects and models of 'Dreamspace Adventures'. (See [[index]] for a brief list of manipulable modules, or the below API Reference for more comprehensive detail.)
#### The REST standard and our deviations #### The REST standard and our deviations
This API very loosely follows an HTTP API architectural standard known as 'REST'. See the following resources for an introduction to this standard, the HTTP protocol, as well as the definition of some key terms used in HTTP API development (and this documentation). This API very loosely follows an HTTP API architectural standard known as 'REST'. See the following resources for an introduction to this standard, the HTTP protocol, as well as the definition of some key terms used in HTTP API development (and this documentation).
@@ -13,8 +13,8 @@ This API very loosely follows an HTTP API architectural standard known as 'REST'
- https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview - https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview
- Note that libraries do 90% of the communication layer work described here. - Note that libraries do 90% of the communication layer work described here.
Now that you have read that, you need to know the design of this API actually deviates in the following signficiant ways from the REST standard: Now that you have read that, you need to know the design of this API actually deviates in the following significant ways from the REST standard:
- The `PUT` method is meant to be an idempotent version of the creation method `POST`, used to update an existing resource or create a resource with a given ID. We do ***not*** follow thise. We currently only use `PUT` in one route, which is to upload a list of stamps (e.g. adding multiple stamps to a document at once). - The `PUT` method is meant to be an idempotent version of the creation method `POST`, used to update an existing resource or create a resource with a given ID. We do ***not*** follow this. We currently only use `PUT` in one route, which is to upload a list of stamps (e.g. adding multiple stamps to a document at once).
- The `POST` method is supposed to always create a new resource if possible. However, `POST /users` specifically does *not* create a new resource if a user with the given `twitch_id` already exists, and it instead *updates* the user, similar to a `PATCH` request. - The `POST` method is supposed to always create a new resource if possible. However, `POST /users` specifically does *not* create a new resource if a user with the given `twitch_id` already exists, and it instead *updates* the user, similar to a `PATCH` request.
- We do not return any 'positive' response code except `200 OK`. In particular we do not return '201 Created', '202 Accepted', '204 No Content'. This is an oversight on my part and may be remedied in future. - We do not return any 'positive' response code except `200 OK`. In particular we do not return '201 Created', '202 Accepted', '204 No Content'. This is an oversight on my part and may be remedied in future.
- After creating a resource (e.g. via `POST /users`), we do not return the location of the resource in the 'Location' header. Instead, we return the newly created resource, which will always include a unique ID that may be used to fetch it again. E.g. `POST /users` will return a User which has a `user_id`. - After creating a resource (e.g. via `POST /users`), we do not return the location of the resource in the 'Location' header. Instead, we return the newly created resource, which will always include a unique ID that may be used to fetch it again. E.g. `POST /users` will return a User which has a `user_id`.
@@ -29,7 +29,7 @@ Content-Type: application/json
Each request will return a JSON-encoded body as well. Either a JSON object for single-object endpoints (such as `/users/1`), or a JSON list for multi-object endpoints (such as `/users` or `/document/1/stamps`). Each request will return a JSON-encoded body as well. Either a JSON object for single-object endpoints (such as `/users/1`), or a JSON list for multi-object endpoints (such as `/users` or `/document/1/stamps`).
#### Dates and times #### Dates and times
Dates and times are represented using the ISO 8601 standard. Note that these should typically include the timezone offset, both upon sending and recieving, and the client is responsible for converting responses and queries to the correct timezones. Dates and times are represented using the ISO 8601 standard. Note that these should typically include the timezone offset, both upon sending and receiving, and the client is responsible for converting responses and queries to the correct timezones.
#### Other notes #### Other notes
- No ratelimiting is implemented (but please don't continuously flood the server). - No ratelimiting is implemented (but please don't continuously flood the server).
@@ -53,7 +53,7 @@ If authentication fails, then HTTP code `403 Not Authorized` is returned.
### Our Model Structure ### Our Model Structure
This API manipulates 6 related models, namely `User`, `Transaction`, `Specimen`, `Event`, `Document`, and `Stamp`. This API manipulates 6 related models, namely `User`, `Transaction`, `Specimen`, `Event`, `Document`, and `Stamp`.
Each model (e.g. `User`) may mnemocially be thought of as a 'directory' (e.g. `/users`), with 'subdirectories' given by the unique ID of that object (e.g. `/users/1`). (Note that the UID used here is an *internal* unique ID roughly correlated to when the object was created on the server, not at all related to e.g. the twitch ID.) Each model (e.g. `User`) may mnemonically be thought of as a 'directory' (e.g. `/users`), with 'subdirectories' given by the unique ID of that object (e.g. `/users/1`). (Note that the UID used here is an *internal* unique ID roughly correlated to when the object was created on the server, not at all related to e.g. the twitch ID.)
The model inter-relationships may be summarised as follows: The model inter-relationships may be summarised as follows: