Overview

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

Structure

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

N.B. PUT is never used to update files that already exist, only to create new files and folders

Hierarchy

The overall structure of the novem API is divided into 5 main parts /vis, /admin, /devs, /groups and /orgs.

  • the /vis endpoints used to create our primary products: plots, mails, docs, grids, and views
  • the /admin endpoints used to control your profile, groups, devices and organisations.
  • the /groups and /orgs endpoints list the groups and organisations your’re currently a member of

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.

Interacting with the API

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

Content-Type

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.

Viewing the output

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.

Sharing novem visuals

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 - the plot is shared with the user smith.
  • @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.

More details on sharing can be found here.

Examples

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.

Plot

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.

E-Mail

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
← Quick Start
Slicing →