Kilonova API Documentation

The Kilonova API is a pretty large, poorly documented beast. In this post, my aim is to demystify some aspects and document a few popular endpoints.

NOTE: This post, like the API, is still a work in progress. I will try my best to announce when breaking changes occur.

Good citizen rules

• Please do not spam my endpoints, I might have to IP/UA block you;
• If you can, try to use a unique user agent in custom clients;
• This API is provided for people to do cool stuff and could be considered a public good, don't abuse it maliciously;
• For now, only the authorization scheme for the main website is present. When (or rather, if) I implement OAuth authorization, I'd like clients to switch to it;
• If you are not authenticated, when requesting, please set the Authorization header to "guest".

With this out of the way, let's get started.

Conventions

• In the following text, when I specify an endpoint, like /submissions/get, I am omitting the /api prefix in the URI and the domain name. So, in this case, the full endpoint would be https://kilonova.ro/api/submissions/get.
• Currently, most POST endpoints support only urlencoded parameters, but I'm slowly adding the ability to accept both JSON and urlencoded parameters in most endpoints.
• This API uses only GET and POST requests, no PUT, PATCH, DELETE.
• When discussing access levels, most endpoints will have something along the lines of MustBeAdmin, MustBeProposer, MustBeAuthed, etc. This is how I also structured my code and it's easier to talk about it this way.
• When there's an endpoint with an ID in the path scheme, those endpoints always validate the user and return a 404 or 400 in case of errors.
• An API response is in JSON format, with the following structure:

// On error
{"status": "error", "data": "<string with user-readable explanation"}
// On success
{"status": "success", "data": <object or scalar returned by API>}

In hindsight, this response format is a bit dumb, since the status can be inferred from the status code, but it's a technical debt I acquired over the past 3 years. A possible v2 to this API would probably only return the "data" object.

Authorization

The current authorization scheme is as follows:

• The API endpoints accept an "Authorization" header, with the session ID as the value.
• Adding something like "bearer" at the beginning is not valid, since it's a randomly generated string, not a JWT token.
• A session ID (which is more like a login token, in this case) lasts for 30 days from when it was created. There is currently no way of querying more information such as the remaining time, but probably the session v2 API in the future will be able to return more information.
• The session can be extended using /auth/extendSession, simply supply the Authorization header. The API response is the new expiration date.

It isn't that complicated, honestly.

Authentication

There are currently 3 endpoints for authentication:

• POST /auth/signup, with the following query parameters:
  • username - the username for the new account
  • email - the email for the new account
  • password - self explanatory, must be between 6 and 72 characters in length
  • language - must be either "" (defaults to platform default), "en" or "ro", can be used to specify the default language in custom interfaces (alongside the official one). Can be changed later
  • theme - must be either "" (defaults to dark mode), "light" or "dark", can be used to specify the default theme in custom interfaces (alongside the official one). Can be changed later
  • The response data is the session ID auto generated for the new account. Details such as user ID can be obtained with /user/getSelf
• POST /auth/login, with the following query parameters:
  • username and password - strings used to authenticate the user
  • The response data is the session ID auto generated for the new account. Details such as user ID can be obtained with /user/getSelf
• POST /auth/logout (MustBeAuthed):
  • Takes no parameters, but it takes the authorization header
  • Removes the session ID from the database