Dreamspace/adventures
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix some more typos.

holo
2025-06-18 23:16:07 +10:00
parent 536ac10fec
commit 3181cde304
1 changed files with 8 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
api-client.md

@@ -9,6 +9,7 @@ This API supports CRUD (Create, Read, Update, and Delete) operations for the obj
#### 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).
- https://blog.postman.com/what-are-http-methods/ - https://blog.postman.com/what-are-http-methods/
- https://restfulapi.net/http-methods/
- https://en.wikipedia.org/wiki/Query_string - https://en.wikipedia.org/wiki/Query_string
- 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.
@@ -29,7 +30,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 receiving, and the client is responsible for converting responses and queries to the correct timezones. Dates and times are represented by strings using the ISO 8601 standard, for example `2025-06-08T20:12:00+10:00`. Note that these should nearly always include the timezone offset (here `+10:00`), both upon sending and receiving, and the client is responsible for converting responses and queries to the correct timezones. If a timestamp is sent without a datetime offset, then it will be converted into the timezone of the server, which is not usually what you want.
#### 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,14 +54,14 @@ 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 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.) Each model (e.g. `User`) may mnemonically be thought of as stored in a 'directory' (e.g. `/users`), with 'files' or '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 corresponding directories are then `/users`, `/transactions`, `/specimens`, `/events`, `/documents`, and `/stamps`.
The model inter-relationships may be summarised as follows: The model inter-relationships may be summarised as follows:
- Users have events, and each Event has a user. - Users have events, and each Event has a user.
- Users have specimens, and each Specimen has an owner. - Users have specimens, and each Specimen has an owner.
- Users have transactions, and each Transaction has a user. - Users have transactions, and each Transaction has a user.
- Events *may* have a document. Documents *do not* have an event. - Events *may* have a document. Documents *do not* have an event.
- Documents have stamps, and each Stamp has a document. - Documents have stamps, and each Stamp has a document.
@@ -71,10 +72,10 @@ Similarly, `/events/1/document` represents the document for event number 1, whic
### CRUD operations ### CRUD operations
The following sections describes how to do each of Create, Read, Update, and Delete with this API. The following sections describes how to do each of Create, Read, Update, and Delete with this API.
I suggested playing around with the examples in Postman so you get a feel how they work. I suggested playing around with the examples in Postman so you get a feel for how they work.
#### Getting objects #### Getting objects
To list the contents of one of these directories, use `GET` requests. To list the contents of one of the model directories, use a `GET` request.
For example, `GET /users` will return all the users known by the API. For example, `GET /users` will return all the users known by the API.
To filter these users, various *search parameters* are supported, which must be added as query parameters to the URI. For example, `GET /users?twitch_id=100` will return a list of users whose `twitch_id` is `100` (in practice, this filter will return either one or no users). Search parameters may also be combined, for example, `GET /events?event_type=plain&created_after=2025-01-01&document_seal=1` will return all the events with type `plain`, created in `2025`, and with seal number `1`. See the chapters in the API Reference below for the accepted search parameters for each model. To filter these users, various *search parameters* are supported, which must be added as query parameters to the URI. For example, `GET /users?twitch_id=100` will return a list of users whose `twitch_id` is `100` (in practice, this filter will return either one or no users). Search parameters may also be combined, for example, `GET /events?event_type=plain&created_after=2025-01-01&document_seal=1` will return all the events with type `plain`, created in `2025`, and with seal number `1`. See the chapters in the API Reference below for the accepted search parameters for each model.
@@ -138,7 +139,7 @@ Add the stamp:
POST /stamps POST /stamps
{ {
"document_id": 21, "document_id": 21,
"stamp_type": "approve", "stamp_type": "Approve",
"pos_x": 0, "pos_x": 0,
"pos_y": 0, "pos_y": 0,
"rotation": 0.0 "rotation": 0.0
@@ -201,7 +202,7 @@ Returns:
} }
``` ```
However, the *implicit* creation flow, allows us to do all the above steps with one request, implicitly creating the document, its stamps, and the user if required. However, the *implicit* creation flow, allows us to do all the above steps with one request, implicitly creating the document, its stamps, and the user if required.
``` ```json
POST /events POST /events
{ {
"document": { "document": {