Files

This document explains the input and output files provided by the novem api.

Overview #

Novem is heavily inspired by the unix philosophy of “everything is a file”. As such our API is implemented as a hierarchical file system that can be mounted on your local disk using our fuse library.

As part of this we wanted to make sure that these virtual files supported sensible extension and content expectations. This document provides a short overview of the kind of files you can expect to find in the novem api and how to interact with them.

Inputs #

All of our interactions are performed by standard HTTP VERBS over HTTPS. If an operation requires submitting data, this is done by providing utf-8 encoded plain text as the body of the post request.

There are a few exceptions, such a registering user accounts, but thoser are marked as system_dir and system_file and can safely be ignored when interacting with the API. (There are separate workflows for signing up with novem.)

Output #

Output formats can vary a bit more than the plain text of the input, but mostly you’ll encounter either json, for visualisations or dir entires, and plain text for control and data files.

However, we appreciate that our output should be consumed in other formats than viewing the web presentations or the e-mails, so there is also a collection of special purpose output formats our users can access.

There outpus are accessible in two different ways, either by appending the corresponding extension to the canonical url of our charts or by accessing the file in the individual visualisations /files folder.

Formats #

Different visaulisations support differnt output formats, both depending on the type of visualisation (mail, plot, grid, doc) and the individual subtypes (table plot vs line plot).

If you’re curious what types are avaiailable you can always list the content of the visuals /files folder, but we’ve provided a rought overview below as well. Further details should also be available under the individual documentation sections, see their various ouput sections.

Portable Document Format pdf #

The Portable Document Format, or PDF, developed by Adobe in the ’90s is the current gold standard in document sharing. Mostly because it always looks the same and prints pretty well.

At novem we still prefer to print our documents for meetings, deep-thought and offline reading, but even if you prefer a tablet, PDF is still a good format.

It was important to us that our documents would look good when printing so we’ve created a separate rendering pipeline for our PDF documents to make sure we get the best experience.

You can control several aspects of the pdf rendering process under the /config/render endpoint for the relevant visuals.

Portable Network Graphics png #

Whilst PDF is the gold standard for document, PNG is a really good format for digitally drawn images. Whilst not as rich a control set as for our pdf files, our visuals also offers png versions of their output.

American National Standards Institute Escape Codes ansi #

Whilst novem was initially intended to let you create web visualisations from the command line, the advent of cool services such as wttr.in inspired us to try and creat an ascii art version as well.

If you try to curl <url> of any of our visuals that support an ansi output you should recieve the ansi version instead. You can also add the .ansi extension for an explicit request.

The ansi version uses 256color ansi escape code and utf-8 box drawing and braille charracters. To see if your current terminal and font supports it try curl -L novem.no/terminal.

Text txt #

The text version is simply the above ansi version with the control charracters stripped out (so no colors).