From 068078a47bac67bd016fd57b85a1be5d18d3576c Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Fri, 29 Oct 2021 14:04:24 +0200 Subject: [PATCH 1/4] add new file action to app provider docs --- docs/extensions/storage/apps.md | 54 +++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/extensions/storage/apps.md b/docs/extensions/storage/apps.md index 19826cf485..9e0cb865cd 100644 --- a/docs/extensions/storage/apps.md +++ b/docs/extensions/storage/apps.md @@ -271,6 +271,60 @@ There are apps, which need to be opened in the iframe with a GET request. The GE } ``` +### Creating a file with the app provider + +**Endpoint**: specified in the capabilities in `new_file_url`, currently `/app/new` + +**Method**: HTTP POST + +**Authentication** (one of them): + +- `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in oCIS) +- `Public-Token` header with public link token for public links +- `X-Access-Token` header with a REVA token for authenticated users + +**Query parameters**: + +- `filename` (mandatory): path / name of the new file +- `template` (optional): not yet implemented + +**Request examples**: + +```bash +curl -X POST 'https://ocis.test/app/new?filename=/home/test.odt' +``` + +**Response example**: + +You will receive a file id of the freshly created file, which you can use to open the file in an editor. + +```json +{ + "file_id": "ZmlsZTppZAo=" +} +``` + +**Example responses (error case)**: + +- #TODO: file already exists, currently existing files will be overwritten + + ```json + { + "code": "ERROR", + "message": "file already exists" + } + ``` + +- unauthorized / failed to create the file + + ```json + { + "code": "SERVER_ERROR", + "message": "error creating resource" + } + ``` + + ## App drivers App drivers represent apps, if the app is not able to register itself. Currently there is only the CS3org WOPI server app driver. From a713c90841510b59cb1c00005eb6e1f7001d93ea Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Thu, 4 Nov 2021 17:06:09 +0100 Subject: [PATCH 2/4] adapt to changes of cs3org/reva#2210 --- docs/extensions/storage/apps.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/extensions/storage/apps.md b/docs/extensions/storage/apps.md index 9e0cb865cd..db7d873622 100644 --- a/docs/extensions/storage/apps.md +++ b/docs/extensions/storage/apps.md @@ -285,13 +285,14 @@ There are apps, which need to be opened in the iframe with a GET request. The GE **Query parameters**: -- `filename` (mandatory): path / name of the new file +- `parent_container_id` (mandatory): ID of the folder in which the file will be created +- `filename` (mandatory): name of the new file - `template` (optional): not yet implemented **Request examples**: ```bash -curl -X POST 'https://ocis.test/app/new?filename=/home/test.odt' +curl -X POST 'https://ocis.test/app/new?parent_container_id=c2lkOmNpZAo=&filename=test.odt' ``` **Response example**: @@ -306,21 +307,37 @@ You will receive a file id of the freshly created file, which you can use to ope **Example responses (error case)**: -- #TODO: file already exists, currently existing files will be overwritten - +- missing parent folder ID ```json { - "code": "ERROR", - "message": "file already exists" + "code": "INVALID_PARAMETER", + "message": "Missing parent container ID" } ``` -- unauthorized / failed to create the file +- missing file name + ```json + { + "code": "INVALID_PARAMETER", + "message": "Missing filename" + } + ``` + +- file already exists ```json { "code": "SERVER_ERROR", - "message": "error creating resource" + "message": "The file already exists" + } + ``` + +- unauthorized / failed to find the parent folder + + ```json + { + "code": "RESOURCE_NOT_FOUND", + "message": "The parent container is not accessible or does not exist" } ``` From 34b2971cb9b06e3e29feaea27e798eb4b7767785 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Thu, 4 Nov 2021 17:10:19 +0100 Subject: [PATCH 3/4] add default_application from cs3org/reva#2230 --- docs/extensions/storage/apps.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/extensions/storage/apps.md b/docs/extensions/storage/apps.md index db7d873622..eeed7955a9 100644 --- a/docs/extensions/storage/apps.md +++ b/docs/extensions/storage/apps.md @@ -132,7 +132,8 @@ curl 'https://ocis.test/app/list' "name": "OpenDocument", "icon": "https://some-website.test/opendocument-text-icon.png", "description": "OpenDocument text document", - "allow_creation": true + "allow_creation": true, + "default_application": "Collabora" }, { "mime_type": "text/markdown", @@ -145,7 +146,8 @@ curl 'https://ocis.test/app/list' ], "name": "Markdown file", "description": "Markdown file", - "allow_creation": true + "allow_creation": true, + "default_application": "CodiMD" }, { "mime_type": "application/vnd.ms-word.document.macroenabled.12", From 11a98997356e0e6b56b716a20d79167c9cb7be00 Mon Sep 17 00:00:00 2001 From: Willy Kloucek Date: Fri, 5 Nov 2021 12:44:15 +0100 Subject: [PATCH 4/4] add https status codes --- docs/extensions/storage/apps.md | 121 ++++++++++++++++++++++++++------ 1 file changed, 99 insertions(+), 22 deletions(-) diff --git a/docs/extensions/storage/apps.md b/docs/extensions/storage/apps.md index eeed7955a9..aa7247828c 100644 --- a/docs/extensions/storage/apps.md +++ b/docs/extensions/storage/apps.md @@ -101,6 +101,8 @@ curl 'https://ocis.test/app/list' **Response example**: +HTTP status code: 200 + ```json { "mime-types": [ @@ -218,6 +220,8 @@ All apps are expected to be opened in an iframe and the response will give some There are apps, which need to be opened in the iframe with a form post. The form post must include all form parameters included in the response. For these apps the response will look like this: +HTTP status code: 200 + ```json { "app_url": "https://.....", @@ -232,6 +236,8 @@ There are apps, which need to be opened in the iframe with a form post. The form There are apps, which need to be opened in the iframe with a GET request. The GET request must have set all headers included in the response. For these apps the response will look like this: +HTTP status code: 200 + ```json { "app_url": "https://...", @@ -246,30 +252,69 @@ There are apps, which need to be opened in the iframe with a GET request. The GE **Example responses (error case)**: -- wrong `view_mode` +- missing `file_id` + + HTTP status code: 400 ```json { - "code": "SERVER_ERROR", - "message": "Missing or invalid viewmode argument" + "code": "INVALID_PARAMETER", + "message": "missing file ID" + } + ``` + +- wrong `view_mode` + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "invalid view mode" } ``` - unknown `app_name` + HTTP status code: 404 + ```json { - "code": "SERVER_ERROR", - "message": "error searching for app provider" + "code": "RESOURCE_NOT_FOUND", + "message": "error: not found: app 'Collabor' not found" } ``` -- wrong / invalid file id / unauthorized to open the file +- wrong / invalid file id + + HTTP status code: 400 ```json { - "code": "SERVER_ERROR", - "message": "error statting file" + "code": "INVALID_PARAMETER", + "message": "invalid file ID" + } + ``` + +- file id does not point to a file + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "the given file id does not point to a file" + } + ``` + +- file does not exist / unauthorized to open the file + + HTTP status code: 404 + + ```json + { + "code": "RESOURCE_NOT_FOUND", + "message": "file does not exist" } ``` @@ -309,37 +354,69 @@ You will receive a file id of the freshly created file, which you can use to ope **Example responses (error case)**: -- missing parent folder ID +- missing `parent_container_id` + + HTTP status code: 400 + ```json { "code": "INVALID_PARAMETER", - "message": "Missing parent container ID" + "message": "missing parent container ID" } ``` -- missing file name +- missing `filename` + + HTTP status code: 400 + ```json { "code": "INVALID_PARAMETER", - "message": "Missing filename" + "message": "missing filename" + } + ``` + +- parent container not found + + HTTP status code: 404 + + ```json + { + "code": "RESOURCE_NOT_FOUND", + "message": "the parent container is not accessible or does not exist" + } + ``` + +- `parent_container_id` does not point to a container + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "the parent container id does not point to a container" + } + ``` + +- `filename` is invalid (eg. includes a path segment) + + HTTP status code: 400 + + ```json + { + "code": "INVALID_PARAMETER", + "message": "the filename must not contain a path segment" } ``` - file already exists - ```json - { - "code": "SERVER_ERROR", - "message": "The file already exists" - } - ``` - -- unauthorized / failed to find the parent folder + HTTP status code: 403 ```json { - "code": "RESOURCE_NOT_FOUND", - "message": "The parent container is not accessible or does not exist" + "code": "RESOURCE_ALREADY_EXISTS", + "message": "the file already exists" } ```