## Apologue and Parable as a Service

Up to this point Apologue has used a simple custom backend. This has worked, but has some limitations that are annoying to me.

* Each evaluation is done in a completely new session
* The results sets are pretty big
* It's all or nothing: if anything goes wrong, you're stuck with a broken JSON document at best or garbage at worst
* Small changes to output can break Apologue

Parable as a Service (begun with the 2016.02 release) will become very important as a means of resolving these issues. It already resolves my biggest issues:

* Snapshot based, so allows for incremental compilations/evaluations
* Results are much smaller: snapshots are compressed, and other requests return smaller, specific pieces of data
* Each request returns specifically requested data only, not the entire result space
* I'll be able to add new features and improve existing ones with less impact to front ends using the API

Currently the only thing using PaaS is *netlistener*. This is currently slow, but should improve as the offline support code is written / fleshed out and fewer network requests are required.

PaaS will be a big part of the initial work done for Parable 2016.04 (work on this starts next week). Part of what I've been waiting on is the opportunity to switch to Python 3 only. This is finally on the horizon (I was holding off due to Pythonista on iOS; there's now a beta with Python 3 support. It works fine for my uses, and I'm hopeful that it'll be publically released in the next couple of months.)

## The API

As it currently stands the API consists of the following requests.

### getpso

First you'll need a snapshot. You can use one created with *gen-snapshot.py* or obtain one via the API:

    req=getpso

Returns a snapshot

### evaluate

    req=evaluate
    pso=snapshot string
    source=string of code to evaluate

Returns a snapshot

### dictionary

    req=dictionary
    pso=snapshot string

Returns a JSON data with keys: names, pointers.

### stack

    req=stack
    pso=snapshot string

Returns a JSON data with keys: values, types.

### dictionary_names

    req=dictionary_names
    pso=snapshot string

Returns a comma separated list of names in the dictionary

### dictionary_map

    req=dictionary_map
    pso=snapshot string

Returns a comma separated list of pointers in the dictionary

### stack_values

    req=stack_values
    pso=snapshot string

Returns a comma separated list of values on the stack. These are raw numbers: use the stack_types to help map these to human readable data.

### stack_types

    req=stack_types
    pso=snapshot string

Returns a comma separated list of type constants for values on the stack. Pair with stack_values to help create human readable data.

### errors

    req=errors
    pso=snapshot string

Returns a comma separated list of error messages. Use clear_errors to empty the error log.

### clear_errors

    req=clear_errors
    pso=snapshot string

Returns a snapshot.

### get_slice

    req=get_slice
    pso=snapshot string
    s=slice number

Returns the memory values in a given slice. These are the raw values without type information.

## Future API Additions

At a minimum I need to implement the following to round out the core functionality.

### get_types

    req=get_types
    pso=snapshot string
    s=slice number

Return the type constants for the values in a given slice.

### get_dependencies

    req=get_dependencies
    pso=snapshot string
    s=slice number

Return a comma separate list of slices that are needed for execution of a specified slice.