........           .........                           .........             
                   _d8888888888888b_  _d8888888888888b_                   _d8888888888888b_         
                .d88888888888888888bvd88888888888888888b.              .d888888888888888888b.       
              .p888888888888888888bd888888888888888888888q.          .p8888888888888888888888q.     
             .d888888888888888888bd88888888888888888888888b.        .d888888888888888888888888b.    
            .d888888888888888888bd8888888888888888888888888b.      .d88888888888888888888888888b.   
            :888888888888888888bd888888888888888888888888888:      :8888888888888888888888888888:   
            :888888888888888888bd888888888888888888888888888:      :8888888888888888888888888888:   
            :888888888888888888bd888888888888888888888888888:      :8888888888888888888888888888:   
            `p88888888888888888bp88888888888888888888888888q'      `p88888888888888888888888888q'   
             `p88888888888888888bp888888888888888888888888q'        `p888888888888888888888888q'    
              `b88888888888888888bp8888888888888888888888d'          `b8888888888888888888888d'     
                `q88888888888888888qp888888888888888888p'              `q888888888888888888p'       
                  `^q888888888888p^` `^q888888888888p^`                  `^q888888888888p^`         
                       ''''''''           ''''''''                            ''''''''              
                                                                                                              
                                  novem.no - datavisualisation for coders

       *** Warning ***  Novem is currently in Alpha and the api is subject to change  *** Warning *** 


 #  Welcome

    Hi and welcome to the novem API.

    This domain contains the api services for the novem datavisualisation platform. If this is not what
    you're looking for perhaps you should check out https://novem.no instead.

    If you do find the details of the novem api interesting then the most up to date information can be
    found at https://novem.no/docs/api/overview/


 #  An introduction to the novem API

    The novem api is inspired by the ideas developed at Bell Labs[1][2] in the late 80s, in particular
    the concepts around using a hierarchical file systems as a unified interface for system integration.

    At the core of the novem API you'll find a tree structure similar to that of a normal unix file
    system. You'll find files and folders with permissions and actions you can perform such as create,
    write, update and delete.

    Now, you may ask why create a service in 2022 based on 40year old technology? Well, we believe that
    the motivation pushing the researchers at bell labs to integrate distributed systems back then is
    just as relevant today, and that the file and folder abstraction is particularly useful for a
    datavisualisation platform like novem.

    We find that examples are better than words, so below you can find some general use cases when it
    comes to data visualisation workflows, and how it maps to our FUSE[3][4] mounted API endpoints.


 #  Creating a new chart

    The novem API offers several visualisation related services, from simple plots all the way up to
    e-mails, documents and even hardware devices. A core strength of our API model is that it allows us
    to create a single, discoverable and uniform interface across all these categories.

    For example, to create a new bar plot all you need to do is to create a new folder in the
    ~/novem/vis/plots/ directory and set the type to be bar (assuming the api is mounted on ~/novem):

       mkdir ~/novem/vis/plots/new_plot_name
       echo "bar" > ~/novem/vis/plots/new_plot_name/config/type

    As you can see, the act of creating the new_plot_name folder makes a whole new hierarchy of options
    available. These can be easily inspected like a standard filesystem using commands such as tree.

      # Simplified example structure of a standard novem bar chart

      new_plot_name/              => 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

    Some of these files are writeable and directly manipulates aspects of the visualisation, such as
    type or color. Others are more abstract, such as createing a file named public in the shared/ folder
    to make a plot public. If you're curious about how to view the plot, simply cat the url file:

       cat ~/novem/vis/plots/new_plot_name/url        # => https://novem.no/p/QVgEN

    Or combine it with other unix utilities and send it straight to the browser

       cat ~/novem/vis/plots/new_plot_name/url | xdg-open


 #  Building knowledge

    The hallmark of a good API is that when you obtain new knowledge, it should be applicable in all
    circumstances where a similar intent is to be performed. You'll therefore find that the same logic
    used to create a plot will work for documents, grids, e-mails, views and device dashboards.

    In addition, novem flavored markdown will let you embed novem charts across all your visuals in a
    simple and consistent way. You can embed chart, grids and docs in your documents or e-mails.


 #  Next Steps

    If you like what you see and want to try out novem for yourself then head over to
    https://app.novem.no/register and create a free account.

    If you need some help getting started you'll find a comprehensive guide at
    https://novem.no/docs/getting_started/introduction/

    If you just want to explore the novem api you can find the current version 1 endpoint at
    https://api.novem.no/v1/

    Happy exploring!


 #  Footnotes 

    [1] - bell labs       -  https://en.wikipedia.org/wiki/Bell_Labs
    [2] - plan-9          -  https://9p.io/plan9/about.html
    [3] - FUSE wikipedia  -  https://en.wikipedia.org/wiki/Filesystem_in_Userspace
    [4] - FUSE repo       -  https://github.com/libfuse/libfuse