From 3181cde304535c3ef1b9399fcb5d243b9cb31efd Mon Sep 17 00:00:00 2001 From: holo Date: Wed, 18 Jun 2025 23:16:07 +1000 Subject: [PATCH] Fix some more typos. --- api-client.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/api-client.md b/api-client.md index 03a7a04..db2b66d 100644 --- a/api-client.md +++ b/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 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://restfulapi.net/http-methods/ - https://en.wikipedia.org/wiki/Query_string - https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview - 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`). #### 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 - 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 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: - Users have events, and each Event has a user. - Users have specimens, and each Specimen has an owner. - Users have transactions, and each Transaction has a user. - - Events *may* have a document. Documents *do not* have an event. - 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 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 -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. 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 { "document_id": 21, - "stamp_type": "approve", + "stamp_type": "Approve", "pos_x": 0, "pos_y": 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. -``` +```json POST /events { "document": {