summaryrefslogtreecommitdiffstats
path: root/protocol.txt
blob: d9f861ad5d3d55ded6786a478cc40050af674005 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
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