Guides

API

This document gives a basic introduction to the structure and design of the novem api.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

The novem API resembles a regular hierarchical file system, which consists of folders that contain files or other folders.

The user interacts with the novem API much like they would a regular filesystem, creating, deleting or modifying files. These interactions are done over HTTP, using the following verbs:

  • GET - read a file or folder
  • DELETE - remove a file or folder
  • OPTIONS - get valid operations on the file or folder
  • PUT - Create a file or folder
  • POST - Overwrite the content of a file
  • PATCH - Modify the content of a file

In addition, each HTTP endpoint has a set of permissions similar to a unix filesystem:

  • r - read
  • w - write
  • x - execute
  • d - delete

When using the OPTIONS verb or viewing the GET content of a folder, novem also provides a list of available HTTP verbs that can be used on the endpoint, mostly matching the intention of read, write or delete.

The novem api is located at https://api.novem.io/v1/. For the rest of this document we use the shorthand / to mean the base of the API, so that e.g /whoami corresponds to https://api.novem.io/v1/whoami.

Since novem emulates a basic file system, most paths expect plain text (text/plain).

Note: PUT is never used to update files that already exist, only to create new files and folders

The novem API is organised into a handful of top-level segments:

  • /vis — your primary products: plots, mails, docs, grids and views
  • /code — jobs and repos (the images they build and the jobs that run them)
  • /admin — your profile, groups, organisations, invites, tokens, keys and notifications
  • /devices — your registered devices, including job runners
  • /orgs — the organisations you're a member of
  • /tags — your tagged content (see tags)
  • /users — browse other users' shared content

In addition there are utility endpoints such as /feed, /token and /whoami, the authentication routes, and the short FQNP roots /u and /o for addressing resources by their owner. Groups are reached under /admin/groups and /orgs/:org/groups rather than a top-level path.

When creating a new folder the underlying structure is already populated. for example, creating a plot in the /vis/plots folder will automatically create a folder structure beneath with files such as data, url, shortname and folders such as config and share.

The GET request issued on a folder will return the content of the folder as a list of json objects. Here name represents the resource and uri the path to the resource, permissions represents the "file" permissions and actions the valid HTTP verbs.

When using GET on a file the content of the file will be returned directly.

PUT can be used on folders to create sub-folders, such as PUT /v1/vis/plots/en_letter_freq to create a new plot visualisation named en_letter_freq. These names can only be lowercase alphanumeric characters with optional underscores.

POST is used to write or update the contents of a file. To turn the visualisation above into a bar chart one would POST bar to /vis/plots/en_letter_freq/config/type.

If you no longer have any need for the chart then you can issue a DELETE request such as DELETE /v1/vis/plots/en_letter_freq.

When interacting with the novem API, you will come across two kinds of content types:

  • application/json
  • text/plain

Most of the system will expect input as plain text, but the output is a bit more context dependant.

All novem visualisation generations happens on our servers, and the output is made available to the user in many formats. via

The easiest one is to view the visualisation online by following the url which can be found by using GET on the url endpoint that can be found in the root of all visualisation folders.

We also provide pre-rendered outputs which are located in the files/ folder under each visualisation. Here you have access to both png, pdf, txt and ansi versions.

Novem plots are private to the owner by default, but they can be shared with other user, groups and the world.

The shared/ folder contains an entity for each entity the plot is shared with:

  • @smith~plots - the plot is shared with the plots group created by smith.
  • +company~plots - the plot is shared with the plots group created by the organization company.
  • public - the plot is shared with the world.

Members of the respective user and organisation groups that are created in the shared folder can then view the plot online.

To remove access simply DELETE the corresponding files in the shared/ folder.

The canonical url of an illustration is https://novem.io/TYPE/SHORTNAME where TYPE is the first letter of the visualisation type, such as p for plots or m for mails.

The shortname is a unique alphanumeric combination created when the visualisation is created, and is always available under the shortname endpoint in the root of the visualisation.

The canonical url lets you fetch different versions of the visual by appending an extension such as .png for the png version or .ansi for the ansi version. You may also chain options like .ansi.html.png to get a picture of the html version of the ansi render.

In addition, when using curl against the canonical url the ansi version is returned by default, allowing for an easy preview straight from the terminal.

Throughout these pages you'll find the below layout used multiple times. The structure is used to illustrate how the api is structured and which folders and files belong at what level in the hierarchy.

For illustrative purposes, below is the structure of an individual plot endpoint representing a chart of type bar. All the below underlying structure will be created as soon as you create the initial /vis/plots/ folder.

en_letter_frequency      => Name
├── config               => Configuration options
│   ├── caption          => Caption below chart
│   ├── title            => Title of chart
│   └── type             => bar, sbar, gbar etc...
├── data                 => data to chart
├── description          => Description
├── name                 => Name
└── shared               => Sharing information
    ├── +org~group       => Shared with an org group
    ├── @username~group  => Shared with a user group
    └── public           => Shared with everyone

The above hierarchy contains three folders: en_letter_frequency which is the name of the plot, a configuration folder called config, and the shared folder.

Below is a partial structure for an individual mail endpoint. All the below underlying structure will be created as soon as you create the initial /vis/mails/ folder.

Daily summary
├── config/
│   ├── reply_to      => Should the e-mail include reply_to header
│   ├── size          => The width of the e-mail: xs, s, m, l
│   ├── subject       => Subject
│   ├── theme         => E-mail theme, layout and color
│   └── type          => Type of e-mail, currently only `simple` is supported
├── files/            => Different mail outputs
├── recipients/       => Mail recipients, either @usernames, groups or full mail address
│   ├── bcc
│   ├── cc
│   └── to
├── shared/           => Who is the mail shared with
├── content           => Markdown body of e-mail
├── description       => Description
├── name              => Name
├── status            => Write sent to send, write test to test
└── url

Next
Plots