Overview

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

Structure

The novem api resembles that of a regular hierarchical file system. You have folders which contains files or other folders.

The user interacts with the novem API like they would a regular filesystem, creating, deleting or modifiying files. The transport for this interaction is however an https endpoint and HTTP actions (verbs).

The interactions are translated to HTTP verbs in the following way:

  • 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 access permission similar to a unix filesystem, these are:

  • 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.no/v1/ and for the rest of this document it’s safe to assume that all paths that begin with / actually represents the full path https://api.novem.no/v1/.

One thing to note is that since novem emulates a basic file system, the expected content you write to these files is plain text for most config options, markdown for things such as mails and docs and csv for plot data.

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 /devs endpoint is use to register and interact with your devices
  • the /admin endpoints used to control your profile, groups, devices and organistaions
  • 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 usually 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.

When creating new visualisations, the name assigned to it in the PUT request will also become the unique ID of the visualisations. These IDs can only be lowercase alphanumeric charracters with optional underscores.

Interacting with the API

The GET request issued on a folder will respond with 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 instead.

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.

POST is used to write the content of a file, overriding what is already there, as such to turn the visualisation above into a bar chart one would POST /v1/vis/plots/en_letter_freq/config/type bar

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.

As novem tries to emulate the interactions you would have with a local file systems, the individual files expect simple text strings as their POST body, often just one or two lines.

The structure of the API is encoded in the hierarchy, such as the names of the options under the config/ folder.

Content-Type

When interacting with the novem API there are two kind of content types you’ll come across:

  • application/json
  • text/plain

Most of the system endpoints will interact in json, similarly all folder listings will provide a json structure. If you however interact with any of the files, the content will be in the form of text/plain

Viewing the output

All novem visualisation generations happens on the server side, but the output is available to the user through several means.

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

An alternative is to get one of the 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.

These files are named after the type of visuals, so the png of the plot visual would be files/plot.png, the mail version files/mail.png etc.

Sharing novem visuals

Access to novem plots are controlled on the server side and based on the names of the files located in the shared/ folder. A file with the name public will make a plot visible to the entire world, whether they are logged in to novem or not.

In addition to making a plot public you can also share it with user groups and organisation groups.

A user group consists of an @ followed by a username, then a ~ and a group name. An organisation group consits of a + followed by an organisation name, then a ~ and a group name.

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.

Examples

Throughout these pages you’ll see the below layout used muliple 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 (meta)
├── name                 => Name (meta)
└── 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 along with a shared folder showing which entities the plot is shared with.

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 includ 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 →