Updated Design: Version Control (markdown)

Design:-Version-Control.md

@@ -18,7 +18,7 @@ Use cases include:
  - a user can see a history of versions - showing date/time + comment (aka `git log`)
  - a user can load a previous version into the editor, which, if then deployed becomes a new version
 
-## API
+# API
 
 Whilst clearly influenced by git as a likely common backend, the version control API needs to be careful to abstract the operations it provides sufficiently so that alternative VC systems can be used underneath it. It does not require the full breadth of capability that git provides (branching/merging etc).
 
@@ -33,6 +33,8 @@ The API should also allow a 'user' identified to passed to each of these calls.
 The existing API has separate methods for saving flows and credentials. The new API must version them as a single entity, although underlying implementations may choose to store them separately.
 
 ---
+## Storage API
+
 ### `Storage.init(runtime)`
  - `runtime` : a RED runtime object
 
@@ -51,7 +53,7 @@ Returns a promise that resolves to the combined flow/credential configuration
  - `flowConfig` : the combined flow/credential configuration
  - `options` : _optional_ : an options object that can contain the following properties:
    - `user` : _optional_ : an identifier for the user setting the flows
-   - `description` : _optional_ : a short description to associate with the change
+   - `summary` : _optional_ : a short summary to associate with the change
 
 Returns a promise that resolves to the `id` of the version saved.
 
@@ -61,11 +63,9 @@ Returns a promise that resolves to an array of history entries. Each entry consi
 
  - `id` : the version id
  - `date` : the timestamp of the version (format tbd)
- - `description` : the short description of the change (will have sensible default, or blank, if none specified)
+ - `summary` : the short summary of the change (will have sensible default, or blank, if none specified)
  - `user` : an identifier for the user who saved the version
 
----
-
 ### Notes
 
  - The format of the combined flow/credential configuration is a vital detail that needs some more thinking. The starting point will be the already documented [new flow format](https://github.com/node-red/node-red/wiki/Design%3A-Flow-file-format-v2). With an additional `credential` property at the top level that contains the node credentials.
@@ -73,6 +73,46 @@ Returns a promise that resolves to an array of history entries. Each entry consi
  - An implementation is not required to maintain any history - it could return a single entry from the `getFlowHistory` call. This reduces the burden on implementations
 
 
+## Runtime API
+
+All of the following API calls should include the `Node-RED-API-Version` HTTP Header to be set to `v2`. If that header is not provided, it will assume to be a request to the `v1` level of the API (ie, what we had before we added this functionality).
+
+### `GET /flows/:id`
+
+Returns a flow configuration. If `:id` is not provided, it returns the active flow configuration. If `:id` is provided, it can be used to return a previous version of the flow configuration.
+
+#### Response:
+
+    {
+        id: "flow-version-id",
+        flow: [ {}, {}, {} ]
+    }
+
+
+### `POST /flows`
+
+Updates the current flow configuration. The body can contain an additional `summary` property to associate with the flow version. The runtime will generate an `id` value and return it in the response. The version will also be associated with the user authenticated to make the request.
+
+#### Body:
+
+    {
+        summary: "optional summary",
+        flow: [ {}, {}, {} ]
+    }
+
+#### Response:
+
+    {
+        id: "flow-version-id"
+    }
+
+### `GET /flows/history`
+
+***TBD***
+
+---
+
+
 ## UI Changes
 
 There are two parts additions to the UI: