JsonDerulo-API-Spec/overview.md

Overview

back to index

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:

{
  "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 :

{"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.