Standard Rest API for Software Evolution Library

The Standard Rest API for Software Evolution Library is implemented as a web service which may be accessed through HTTP requests.

It attempts to conform to principals described here: Representational State Transfer

2.6.3.1 Dependencies

The Rest API leverages a number of Common Lisp components, which are open-source and generally available via Quicklisp. See the core REST file for a full description.

2.6.3.2 Dependencies

The Rest API leverages a number of Common Lisp components, which are open-source and generally available via Quicklisp. See the core REST file for a full description and how to start a rest server. In addition, this file is built from the session definitions for REST provided as part of sel.

2.6.3.3 Resources and Operations

A standard sel Rest API supports logical resources. This section lists the basic logical resources supported by this standard API. In some cases (e.g. Software), the resource can be thought to be a distillation of the methods of the matching sel class. In other cases (e.g. Populations) there isn’t a specific class in sel, and the REST API resource provides ways to manage and name these lists of software objects.

Resources

The following types of resources are defined by this standard API.

Software

Any non-abstract class that inherits from software

Mutations

sel mutation objects.

Populations

Collections of software objects, which may change rapidly (evolution).

Test Suites

Lists of Test Cases, which each include references to an executable file and some command-line argumants. These are used to evaluate Software objects.

Operations on Resources

Note: all operations (other than session create) require a cid (Client ID) integer value representing the Client id for session lookup. See the client sessions file for endpoint usage to acquire one.

Software:

post

<service-base>/soft?cid=<cid>&type=<software-type> Body, JSON format, contains path (to C file, AST, Asm file, etc.), or a url to a file, or the actual source code which would comprise the file. If the body simply contains a software id (sid), makes a copy of the software object. All JSON fields which are not [path, url, code, software-id] are passed as keyword parameters to (make-instance '<software-type> &key). Returns a software object id of newly created software.

get

<service-base>/soft?cid=<cid>&sid=<software ID> Returns JSON describing software object (differs depending on type of software).

get

<service-base>/soft?cid=<cid>&type=<software type> Returns IDs of live software objects of the passed type, owned by the client.

get

<service-base>/soft?cid=<cid> Return IDs of all live software objects owned by the client.

put

<service-base>/soft?cid=<cid>&sid=<software ID> Update a software object. Body (json) contains slots to update, new values.

delete

<service-base>/soft?cid=<cid>&sid=<software ID> Delete a software object. (Currently not supported in full -- work in progress.)

Population:

post

<service-base>/cid=<cid>&population?name=<population-name> Creates a Population resource, storing it in the assocaited client session, containing software objects of the specified type. The request should also contain JSON including:

- sid (list) : list of Software IDs (sid) to include in population - type (string) : software type

Returns the id of newly created Population (pid).

put

<service-base>/cid=<cid>&pop?pid=<Population-ID> Adds software to the population. Takes a JSON request containing:

- sid (list) : list of Software IDs (sid) to include in population

It adds the specified sid(s) to the population.

get

<service-base>/cid=<cid>&pop?pid=<Population-ID> Retrieves information about the population, including list of Software IDs and software type.

delete

<service-base>/cid=<cid>&pop?pid=<Population-ID> Delete the population. (work in progress)

Mutation: post @{<service-base>/cid=<cid>&mut?type=<mutation-type>&sid=<software-id>} Body (json) contains targets field (integer, list, or ast). Returns mutation-id (mid).

get

<service-base>/cid=<cid>&mut?mid=<mutation-id> Returns mutation details.

put

<service-base>/cid=<cid>&mut?mid=<mutation-id> Apply mutation to its target software object, returns the sid of the new (mutated) software object.

delete

service-base>/cid=<cid>&mut?mid=<mutation-id> Delete the specified mutation. (work in progress)

Test Suites:

post

<service-base>/tests?cid=<cid> Creates a test-suite instance, owned by the client, containing a collection of test-suite objects. Body should contain "test" field, JSON format, array of structures, each containing program-name and program-args. Returns oid of newly created tests suite.

get

<service-base>/tests?cid=<cid>&oid=<test-suite-oid> Retrieves collection of test cases in the test-suite.

delete

<service-base>/tests?cid=<cid>&pid=<test-suite-oid> Delete the test suite. (work in progress)

Write Software:

post

<service-base>/writesoft?cid=<cid>&sid=<software-oid> Writes the specified software object to a file (to-file). Returns success or error code. Body contains path specification.

Async-Job:

post

<service-base>/async?cid=<cid>&type=<job-type> Body contains (json) parameters for evolve task, fitness-test or other defined type of task. Returns immediately with a Job-ID (jid). Creating a Job starts a task (on a new thread) which will execute until stopped or completed.

get

<service-base>/cid=<cid>&async?jid=<Job-ID> Returns JSON containing job status and results.

put

<service-base>/cid=<cid>&async?jid=<Job-ID>&<update-vars> Allows some control of the task, such as stopping the task.