How Apps Work

An Overview App is a program that uses Overview.

You can make one. You know you want to.

You

We assume:

• You know how to program (in the language of your choice).
• You know how to programmatically send HTTP requests.
• You know a bit of JavaScript.

Standalone Apps

Here's a diagram of a simple app:

Here's what it means:

• Overview is a web service that stores documents.
• Your App is a program that you write (possibly from scratch). Use whatever programming language you like.
• Your App can read and write information on Overview using API methods.
• Overview does not control or restrict your App. You may store as much data as you wish in Overview's databases; you may use as many or as few API calls as you wish.

What an app looks like

Here's an example simple Node app, written in JavaScript. It searches for documents containing the word "word" and then tags them.

Warning Overview's API isn't complete yet! These methods might not all work.

var documentSetId = 1; // REPLACE ME
var apiToken = 'api-token'; // REPLACE ME
var search = 'word'; // REPLACE ME
var request = require('request');

function path(end) {
  return 'https://www.overviewproject.org/api/v1/document-sets/' + documentSetId + end;
}

var req = request.defaults({
  auth: { user: apiToken, pass: 'x-auth-token' }
});

function GET(path, done) {
  req.get(path(path), done);
}

function POST(path, json, done) {
  req.post({ url: path(path), method: 'post', json: json }, done);
}

console.log('Fetching list of document IDs containing search string', search);
GET('/documents?fields=id&q=' + encodeURIComponent(search), function(error, response, ids) {
  if (error) throw error;

  if (ids.length == 0) {
    console.log('No matches. Exiting.');
  } else {
    console.log('Number of matches:', ids.length);

    console.log('Creating tag');
    POST('/tags', { title: "App search results: " + search }, function(error, response, tag) {
      if (error) throw error;

      console.log('Tagging documents');
      var idPairs = ids.map(function(id) { return [ id, tag.id ] });
      POST('/document-tags', idPairs, function(error, response, body) {
        console.log('Tagged ' + body.length + ' documents');
      }));
    }));
  }
}));

Can I do [IMPORTANT THING]?

You can do anything. The API gives you complete access to your documents.

View Apps

A standalone app is missing a user interface. You can make your standalone app into a full-fledged web server, but you'll probably need to re-implement search, tags, document lists, and so on.

You're probably using Overview because you don't hate the website. Now you can put your program in Overview, like this:

Here's a diagram of how the pieces fit together:

Here's what's different:

• Your App is a web server
• Overview includes your App in an <iframe> element
• Overview passes your App server, documentSetId, vizId and apiToken, by opening the URL https://your.app/show?server=https%3a%2f%2fwww.overviewproject.org&apiToken=api-token&documentSetId=123&vizId=456
• Your App still reads and writes using the Overview API
• Your App's iframe and the main page communicate using Window.postMessage
• Your App can alter the "selection", which is the set of parameters that decides what's in the document list. The Overview API server may query your App to translate the "selection" to a list of document IDs.

Whoa, isn't a whole web server a lot of work?

We're talking a minimal web server:

• You don't need to store anything. Overview can handle storage for you.
• You only need to handle two routes: /metadata and /show.
• You don't need server-side logic. /metadata and /show can be flat files.
• You don't need any background processes.

Start by hosting flat files somewhere. You can code everything in JavaScript. Then if you want to add advanced features such as selections, add server-side logic.

On the other hand, you may prefer to code background processes and lots of routes. If so, go for it!