diff options
Diffstat (limited to 'overview.md')
| -rw-r--r-- | overview.md | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/overview.md b/overview.md new file mode 100644 index 0000000..6b01e3e --- /dev/null +++ b/overview.md @@ -0,0 +1,91 @@ +# Overview + +[back to index](README.md) + +## Base URL + +The server listens on `http://<host>:<port>`. Port is configurable, no specific port is required by the spec. but it is advised to use 5777 for internal purposes and 80/443 for External Purposes, If you want HTTPS you need a reverse proxy in front. + +## Content Type + +Everything is JSON (Derulo bahahahahah). Requests and always responses use `Content-Type: application/json`. + +The only exception is when a toolkit endpoint uses `response_format: "passthrough"` for proxying file downloads or something none Jayson from an upstream service. In that case the response mimetype comes from whatever upstream decides to send back. + +## Toolkit and Config file Format : +- All config and toolkit files should use toml + - If you hate toml for whatever reason you can use whatever you want in your implementation with the following two conditions being bundled with the server : + - Built in support for converting the fully speced out reference server's config (SeckelAPI) to your implementations config format + - Built in support for converting to fully compatible reference server's (SeckelAPI) toml files from your implementation config format + - I dont want to make your life pain with this but just like give users the freedom of using a different backend server with ease if one ever comes. (might even happen from my side as seckel api is tbh a bit of a mess lol) + +## Authentication + +Every endpoint requires a session token except these three: + +- `GET /` version info +- `GET /health` service and DB status +- `POST /auth/login` where you get a damn session token in the first place + +Therefore to talk with JsonDerulo get a session token from `/auth/login` and send it on every request after that as `Authorization: Bearer <token>` it's the only way JsonDerulo wants to talk to you! + +## All Ways to talk to JsonDerulo (Endpoints) + +| Method | Path | Auth | What it does | +|----------|-----------------------------|------|------------------------------------------------------| +| GET | `/` | no | version info and stuff | +| GET | `/health` | no | service health and DB connectivity | +| POST | `/auth/login` | no | get a magic session token | +| POST | `/auth/logout` | yes | kill your session :( | +| GET | `/auth/status` | yes | check if your session is still alive | +| POST | `/auth/clear-sessions` | yes | adminier: nuke all sessions for a specific user | +| POST | `/query` | yes | database queries (select insert update delete count) | +| GET | `/permissions` | yes | see what tables and columns you can access | +| POST | `/preferences` | yes | get/set/reset user preferences | +| POST | `/reload` | yes | adminier: hot/hard reload server config | +| POST/GET | `/tk/app/{toolkit}/{*path}` | yes | toolkit application endpoint | +| POST/GET | `/tk/lib/{toolkit}/{*path}` | yes | toolkit library endpoint | + +## Rate Limiting + +Backend should support two separate rate limiters: one for auth routes and one for API routes. +Both are per IP with per second and per minute burst limits and should be capable of detecting external IP addresses (if behind proxi) + +When you get rate limited the JsonDerulo responds with HTTP 429 and a JSON body telling you how long you should simply admire Jaysons Body instead of telling him your Schizophrenic JsonDerulo request, body should look like this: + +```json +{ + "success": false, + "error": "Too many requests. Naughty! Go sit in a corner for 3 Seconds!", + "retry_after": 3 +} +``` + +Rate limiting can be disabled entirely in config but that shouldnt be done in production obviously. + +## Date and Time Formats + +Query responses serialize the upstream database types into JSON like this: + +| MySQL Type | JSON Format | +|--------------------------|-----------------------| +| `DATE` | `YYYY-MM-DD` | +| `DATETIME` | `YYYY-MM-DD HH:MM:SS` | +| `TIMESTAMP` | RFC 3339 string | +| `TIME` | `HH:MM:SS` | +| `BOOLEAN` / `TINYINT(1)` | `true` / `false` | + +(I thought I implemented changing them but idk TODO in v2.1) + +## Request IDs + +Every request gets a unique request_id. It shows up in error messages and audit logs so you can trace stuff if something goes wrong. The length of the request_id is capped at 32 Numbers and shouldnt be shorter than like 8) + +Example : +```json +{"message":"Session expired or invalid [request_id: 10036480868868238719]","success":false} +``` + +## Request Body Limits + +Theres should be configurable max request body size (in KB/MB/GB). Requests bigger than that get rejected. There should however be options to extend this for individual toolkit endpoints if nececsary. |