Direct file upload for substitution

docs/compendium/substitute.md

@@ -1,24 +1,33 @@
 # Substitution
 
-Substitution is the combination of an base compendium, "base" for short, and an overlay compendium, or "overlay".
-A user can choose files from the overlay to replace files of the base, or upload new files.
+Substitution is the combination of an base compendium and an overlay compendium.
+A user can choose files from the overlay compendium that will replace files of the base compendium, or add new files to the substitution.
 
 ## Create substitution
 
-`Create substitution` produces a new compendium with its own files in the storage and metadata in the database.
-A substitution can be created with an HTTP `POST` request using `multipart/form-data` and content-type `JSON`.
-Required content of the request are the identifiers of the base and overlay compendia and at least one pair of _substitution files_, consisting of a base file and an overlay file.
+Creating a substitution produces a new compendium with its own metadata and files.
+A substitution is created with an HTTP `POST` request using `multipart/form-data` and content-type `JSON`.
+Required fields are the identifiers of base compendium and overlay compendium and at least one pair of _substitution files_, consisting of one base file and one overlay file.
 
 !!! Note
     A substitution process removes potentially existing packaging information, i.e. if the base compendium was a BagIt bag, the substitution will only contain the payload directory contents (`/data` directory).
 
     The overlay file is stripped of all paths and is copied directly into the substitution's root directory.
+    The original path is preserved in the substitution metadata.
+
+### Created metadata and files
+
+The substitution creation includes an update of the compendium metadata in the file **`erc.yml`**, which implements the actual substitution.
+After creation, subsequent [jobs](http://o2r.info/o2r-web-api/job/) consider these settings.
+
+The **files** of a substituted compendium comprise all base compendium files and the overlay files.
+In case of a file naming conflict, the overlay file is preprended with `overlay_`.
 
 ### Request
 
 `POST /api/v1/substitution`
 
-Request body for a new substitution:
+**Example** request body:
 
 ```json
 {
@@ -33,13 +42,46 @@ Request body for a new substitution:
 }
 ```
 
+**Example** request body with embedded file upload:
+
+```json
+{
+  "base": "G92NL",
+  "overlay": "9fCTR",
+  "substitutionFiles": [
+    {
+      "base": "climate-timeseries.csv",
+      "overlay": {
+        "filetype": "text/csv",
+        "filename": "my-data.csv",
+        "base64": "aWQsZGF0ZSx0ZW1wZXJhdHVyZVxuMSwyMDE3LTAxLTAxLDE3XG4yLDIwMTctMDEtMDIsNDIK"
+      }
+    }
+  ]
+}
+```
+
+The above example was created as follows:
+
+```bash
+$ echo "id,date,temperature\n1,2017-01-01,17\n2,2017-01-02,42" >> my-data.csv
+$ base64 -w 0 my-data.csv
+aWQsZGF0ZSx0ZW1wZXJhdHVyZVxuMSwyMDE3LTAxLTAxLDE3XG4yLDIwMTctMDEtMDIsNDIK
+$ echo aWQsZGF0ZSx0ZW1wZXJhdHVyZVxuMSwyMDE3LTAxLTAxLDE3XG4yLDIwMTctMDEtMDIsNDIK | base64 -d
+id,date,temperature\n1,2017-01-01,17\n2,2017-01-02,42
+$ mimetype my-data.csv
+my-data.csv: text/csv
+```
+
 ### Request body properties
 
+  - `base` - name of the file from the base compendium
+  - `overlay` - either a reference to a file in the overlay ERC, or embedded file upload
+    - _overlay file_: filename of a file in the overlay ERC, which is exchanged for the file from the base ERC
+    - _file upload_: JSON object with metadata and content of the file in the properties `filetype`, `filename` and `base64`, the latter being a [Base64](https://en.wikipedia.org/wiki/Base64) encoding of the file.
 - `base` - id of the base compendium
 - `overlay` - id of the overlay compendium
 - `substitutionFiles` - array of file substitutions specified by `base` and `overlay`
-  - `base` - name of the file from the base compendium
-  - `overlay` - name of the overlay compendium that is exchanged for the original file
 
 !!! note "Required user level"
 
@@ -81,21 +123,17 @@ Request body for a new substitution:
 {"error":"overlay compendium not found"}
 ```
 
-## View substituted Compendium
+## View substituted compendium
 
 ### Request
 
-`curl https://.../api/v1/compendium/$ID`
-
-`GET /api/v1/compendium/:id`
-
-This request is handled as regular GET request of a compendium (see [View single compendium](http://o2r.info/o2r-web-api/compendium/view/#view-single-compendium)).
+This request is the same as for a regular compendium, see [view compendium](view.md#view-single-compendium).
 
 ### Response
 
 A substituted compendium is be saved as a usual compendium, but with additional metadata specifying this as a substituted compendium and giving information about the substitution.
 
-Example 01 - in case there are no conflicts between filenames of any base file and overlay file :
+**Example** without naming conflicts:
 
 ```json
 200 OK
@@ -114,6 +152,11 @@ Example 01 - in case there are no conflicts between filenames of any base file a
               "base": "climate-timeseries.csv",
               "overlay": "mytimeseries_data.csv",
               "filename": "climate-timeseries.csv"
+            },
+            {
+              "base": "analysis-settings.xml",
+              "overlay": "better-settings.txt",
+              "filename": "analysis-settings.xml"
             }
           ]
       },
@@ -123,7 +166,7 @@ Example 01 - in case there are no conflicts between filenames of any base file a
 }
 ```
 
-Example 02 - in case the overlay file has the same filename as one of the existing base files and is in a sub-directory in the overlay compendium:
+**Example** with naming conflicts and overlay from sub-directory:
 
 ```json
 200 OK
@@ -151,6 +194,8 @@ Example 02 - in case the overlay file has the same filename as one of the existi
 }
 ```
 
+Note that the base file must not be the file causing the naming conflict.
+
 ### Response additional metadata
 
 - `substituted` - is `true`
@@ -162,7 +207,7 @@ Example 02 - in case the overlay file has the same filename as one of the existi
     - `overlay` - filename of the file from the overlay compendium
     - `filename` - as seen in the examples above, `filename` is created if there is a conflict with any base file name and an overlay file name. In this case the overlay file name is given the prefix `overlay_` (see Example 02).
 
-## List substituted Compendia
+## List substituted compendia
 
 ### Request
 
@@ -172,7 +217,7 @@ Example 02 - in case the overlay file has the same filename as one of the existi
 
 ### Response
 
-The result is be a list of compendia ids that have been substituted:
+Result will be a list of compendia ids which are created by a substitution process.
 
 ```json
 200 OK
@@ -187,6 +232,7 @@ The result is be a list of compendia ids that have been substituted:
 }
 ```
 
+### Filter
 If there are no substitutions yet, the returned list is empty.
 
 ```json
@@ -196,13 +242,13 @@ If there are no substitutions yet, the returned list is empty.
 }
 ```
 
-### Filter results with following parameters:
+Results can be filtered with the parameters `base` and `overlay`.
 
 `curl https://.../api/v1/substitution?base=$BASE_ID&overlay=$OVERLAY_ID`
 
 `GET /api/v1/substitution?base=base_id&overlay=overlay_id`
 
-- Filter by `base`:
+**Example** for filtering by `base`:
 
 `curl https://.../api/v1/substitution?base=jfL3w`
 
@@ -221,7 +267,7 @@ Result is a list of compendia ids that have been substituted using the given bas
 }
 ```
 
-- Filter by `overlay`:
+**Example** for filtering by `overlay`:
 
 `curl https://.../api/v1/substitution?overlay=as4Kj`
 
@@ -241,7 +287,7 @@ Result is be a list of compendia ids that have been substituted using the given
 }
 ```
 
-- Filter by `base` and `overlay`:
+**Example** for filtering with both `base` and `overlay`:
 
 `curl https://.../api/v1/substitution?base=lO3Td&overlay=as4Kj`
 
@@ -260,6 +306,11 @@ Result is be a list of compendia ids that have been substituted using the given
 }
 ```
 
+### URL parameters
+
+- `:base` - id of the base ERC of substitutions in the result
+- `:overlay` - id of the base ERC of substitutions in the result
+
 ### Error responses
 
 ```json

docs/o2r.css

@@ -10,13 +10,22 @@
     background-color: #004286;
 }
 
+.wy-menu-vertical a:active{
+    background-color:#004286;
+}
+
 .wy-menu a {
     color: #ffffff;
 }
 
 .wy-menu-vertical a:hover {
 	background:#004286;
 }
+h3, h4, h5, h6 {
+
+    color: #004286;
+    font-weight: 300
+}
 
 .subnav {
     margin-left: 1em;