Files

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 those are marked as system_dir and system_file and can safely be ignored when interacting with the API.

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, or plain text for control and data files.

The output of visualisations can be presented in more ways than viewing the web presentations or the e-mails, so we also provide a collection of special purpose output formats, like PDF or a pre-rendered image.

Their outputs 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 visualisations support different 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 available you can always list the content of the /files folder of the visual, but we’ve provided a rough overview below as well. Further details are also documented under the sections for the different visualisation type.

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.

Many users still prefer to print documents for meetings, analysis and offline reading, and PDF is the go-to format for these use cases.

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 #

While PDF is the gold standard for documents, PNG is an excellent format for digitally rendered images. Although the customization options for PNG files are not as extensive as those for PDF files, our visuals also provide PNG versions of their output for convenient use in digital environments.

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 create an ascii art version as well.

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

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

Text txt #

The text version is a simplified version the above ansi output, but without colors.