# 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.