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.
