diff --git a/docs/compendium/substitute.md b/docs/compendium/substitute.md index 1d69184..9ed3d53 100644 --- a/docs/compendium/substitute.md +++ b/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 diff --git a/docs/o2r.css b/docs/o2r.css index c5cd180..0be375b 100644 --- a/docs/o2r.css +++ b/docs/o2r.css @@ -10,6 +10,10 @@ background-color: #004286; } +.wy-menu-vertical a:active{ + background-color:#004286; +} + .wy-menu a { color: #ffffff; } @@ -17,6 +21,11 @@ .wy-menu-vertical a:hover { background:#004286; } +h3, h4, h5, h6 { + + color: #004286; + font-weight: 300 +} .subnav { margin-left: 1em;