ACF2 HTTP Protocol
==================

Load JavaScript client:
req: GET /

Log in:
req: POST /login
     - body is a JSON object with username and password attributes
resp headers:
     - X-ACF-Auth-Token: authentication token, use in the header of
       subsequent requests
     - X-ACF-Save-Required: if set to 1, an explicit request is
       required to save the changed files persistently

Log out:
req: DELETE /login
     X-ACF-Auth-Token: <token>

Save configuration files persistently (lbu commit):
req: POST /save

Start transaction:
req: POST /transaction
resp: txn ID (in header as X-ACF-Transaction-ID)
      - use X-ACF-Transaction-ID in the header of any subsequent
      	request to process it in the transaction's context
      - nested transactions can be started by using it in a subsequent
      	start transaction request

Commit transaction:
req: PUT /transaction
     X-ACF-Transaction-ID: <txn_id>

Abort transaction:
req: DELETE /transaction
     X-ACF-Transaction-ID: <txn_id>

Get object:
req: GET /config/<obj_path>
resp: JSON object, with the following attributes:
      data: JSON serialization of object
      	    - primitive types as JSON primitives
      	    - references as path names (relative to scope)
      	    - models as JSON objects with members as attributes:
      	      - primitive members as JSON primitives
      	      - reference, model, collection, list, and set members as
	      	path names
      	    - collections, lists, and sets as JSON arrays with members
	      as attributes (as for models)
      meta: JSON object, with the following attributes
      	    - name (last component of path name)
      	    - ui-name (shown to user)
      	    - description (optional help text)
      	    - type (e.g. model, collection, set, reference, string,
	      number, boolean)
      	    - widget (name of client-side JS module used to display
	      the data)
      	    - required (boolean)
	    - default
      	    - max-length
      	    - choices (optional array of allowed values)
      	    - ui-choices (user-friendly choices to be shown in combo
	      boxes)
      	    - fields (model only): array of field metadata JSON
	      objects
      	    - members (collections and sets only): metadata for
	      members (JSON object)
	    - ui-member (collections and sets only): singular noun
	      describing members (shown to user)
      	    - scope (references only): subtree where the reference can
	      refer to

Create/update object:
req: PUT /config/<obj_path>
     - body shall contain the object serialized as the data attribute
       in GET responses
     - undefined model attributes are deleted

Add object to a list:
req: POST /config/<list_path>
     - body is a JSON object with the following attributes:
       data: object to be added, serialized as in GET responses
       index: position, defaults to the end of the list

Delete object:
req: DELETE /config/<obj_path>

Add member to a set:
req: POST /config/<set_path>
     - body shall contain a JSON primitive

Delete set member:
req: DELETE /config/<set_path>/<member>

Invoke object-specific action (not yet supported by server):
req: POST /config/<obj_path>/<action>
     - arguments passed as a JSON array in body; serialization as in
       GET responses
resp: action-specific JSON
      - for time-consuming actions, can return multiple JSON
      	documents, each containing a status update

Get metadata (for a potentially non-existent object):
req: GET /meta/<path>
resp: as the meta attribute in get object response


Use of HTTP status codes:

2xx Success

400 Bad request
    resp: plain text error message

401 Authentication error

403 Forbidden

404 Not found

405 Method not allowed

409 Concurrent modification
    resp: JSON list of objects modified by a concurrent transaction

422 Semantic error
    resp: JSON object mapping paths to object-specific lists of
    	  validation error messages

500 Server error
