From a397984242f0bf95701ae3e4bc37a3a1005634e9 Mon Sep 17 00:00:00 2001 From: jkoberg Date: Tue, 25 Jun 2024 10:55:35 +0200 Subject: [PATCH] fix(docs): remove _index.md from app-registry Signed-off-by: jkoberg --- docs/services/app-registry/_index.md | 493 --------------------------- 1 file changed, 493 deletions(-) delete mode 100755 docs/services/app-registry/_index.md diff --git a/docs/services/app-registry/_index.md b/docs/services/app-registry/_index.md deleted file mode 100755 index bf4f6b6133..0000000000 --- a/docs/services/app-registry/_index.md +++ /dev/null @@ -1,493 +0,0 @@ ---- -title: App Registry -date: 2024-04-08T14:03:04.981194969+02:00 -weight: 20 -geekdocRepo: https://github.com/owncloud/ocis -geekdocEditPath: edit/master/services/app-registry -geekdocFilePath: README.md -geekdocCollapseSection: true ---- - - - -## Abstract - - -The `app-registry` service is the single point where all apps register themselves and their respective supported mime types. - -Administrators can set default applications on a per MIME type basis and also allow the creation of new files for certain MIME types. This per MIME type configuration also features a description, file extension option and an icon. - - -## Table of Contents - -* [MIME Type Configuration / Creation Allow List](#mime-type-configuration-/-creation-allow-list) - * [MIME Type Configuration](#mime-type-configuration) -* [App Drivers](#app-drivers) - * [CS3org WOPI Server App Driver](#cs3org-wopi-server-app-driver) - * [App Provider Configuration](#app-provider-configuration) -* [Endpoint Access](#endpoint-access) - * [Listing available apps and mime types](#listing-available-apps-and-mime-types) - * [Open a File With ownCloud Web](#open-a-file-with-owncloud-web) - * [Open a File With the App Provider](#open-a-file-with-the-app-provider) - * [Creating a File With the App Provider](#creating-a-file-with-the-app-provider) -* [Example Yaml Config](#example-yaml-config) - -## MIME Type Configuration / Creation Allow List - -The apps will register their supported MIME types automatically, so that users can open supported files with them. - -Administrators can set default applications for each MIME type and also allow the creation of new files for certain mime types. This, per MIME type configuration, also features a description, file extension option and an icon. - -### MIME Type Configuration - -Modifing the MIME type config can only be achieved via a yaml configuration. Using environment variables is not possible. For an example, see the `ocis_wopi/config/ocis/app-registry.yaml` at [docker-compose example](https://github.com/owncloud/ocis/tree/master/deployments/examples). The following is a brief structure and a field description: - -**Structure** - -```yaml -app_registry: - mimetypes: - - mime_type: application/vnd.oasis.opendocument.spreadsheet - extension: ods - name: OpenSpreadsheet - description: OpenDocument spreadsheet document - icon: https://some-website.test/opendocument-spreadsheet-icon.png - default_app: Collabora - allow_creation: true - - mime_type: ... -``` - -**Fields** - -* `mime_type`\ -The MIME type you want to configure. -* `extension`\ -The file extension to be used for new files. -* `name`\ -The name of the file / MIME type. -* `description`\ -The human-readable description of the file / MIME type. -* `icon`\ -The URL to an icon which should be used for that MIME type. -* `default_app`\ -The name of the default app which opens this MIME type if the user doesn’t specify one. -* `allow_creation`\ -Whether a user should be able to create new files of that MIME type (true or false). - -## 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. - -### CS3org WOPI Server App Driver - -The CS3org WOPI server app driver is included in Infinite Scale by default. It needs at least one WOPI-compliant app like Collabora, OnlyOffice or the Microsoft Online Server or a CS3org WOPI bridge supported app like CodiMD or Etherpad and the [CS3org WOPI server](https://github.com/cs3org/wopiserver). - -### App Provider Configuration - -The configuration of the actual app provider in a [docker-compose example](https://github.com/owncloud/ocis/tree/master/deployments/examples) can be found in the full `ocis-wopi` example directory especially in the config sections `ocis-appprovider-collabora` and `ocis-appprovider-onlyoffice`. - -## Endpoint Access - -### Listing available apps and mime types - -Clients, for example ownCloud Web, need to offer users the available apps to open files and mime types for new file creation. This information can be obtained from this endpoint. - -**Endpoint**: specified in the capabilities in `apps_url`, currently `/app/list` - -**Method**: HTTP GET - -**Authentication**: None - -**Request example**: - -```bash -curl 'https://ocis.test/app/list' -``` - -**Response example**: - -HTTP status code: 200 - -```json -{ - "mime-types": [ - { - "mime_type": "application/pdf", - "ext": "pdf", - "app_providers": [ - { - "name": "OnlyOffice", - "icon": "https://some-website.test/onlyoffice-pdf-icon.png" - } - ], - "name": "PDF", - "description": "PDF document" - }, - { - "mime_type": "application/vnd.oasis.opendocument.text", - "ext": "odt", - "app_providers": [ - { - "name": "Collabora", - "icon": "https://some-website.test/collabora-odt-icon.png" - }, - { - "name": "OnlyOffice", - "icon": "https://some-website.test/onlyoffice-odt-icon.png" - } - ], - "name": "OpenDocument", - "icon": "https://some-website.test/opendocument-text-icon.png", - "description": "OpenDocument text document", - "allow_creation": true, - "default_application": "Collabora" - }, - { - "mime_type": "text/markdown", - "ext": "md", - "app_providers": [ - { - "name": "CodiMD", - "icon": "https://some-website.test/codimd-md-icon.png" - } - ], - "name": "Markdown file", - "description": "Markdown file", - "allow_creation": true, - "default_application": "CodiMD" - }, - { - "mime_type": "application/vnd.ms-word.document.macroenabled.12", - "app_providers": [ - { - "name": "Collabora", - "icon": "https://some-website.test/collabora-word-icon.png" - }, - { - "name": "OnlyOffice", - "icon": "https://some-website.test/onlyoffice-word-icon.png" - } - ] - }, - { - "mime_type": "application/vnd.ms-powerpoint.template.macroenabled.12", - "app_providers": [ - { - "name": "Collabora", - "icon": "https://some-website.test/collabora-powerpoint-icon.png" - } - ] - } - ] -} -``` - -### Open a File With ownCloud Web - -**Endpoint**: specified in the capabilities in `open_web_url`, currently `/app/open-with-web` - -**Method**: HTTP POST - -**Authentication** (one of them): - -- `Authorization` header with OIDC Bearer token for authenticated users or basic auth credentials (if enabled in oCIS) -- `X-Access-Token` header with a REVA token for authenticated users - -**Query parameters**: - -- `file_id` (mandatory): id of the file to be opened -- `app_name` (optional) - - default (not given): default app for mime type - - possible values depend on the app providers for a mimetype from the `/app/open` endpoint - -**Request examples**: - -```bash -curl -X POST 'https://ocis.test/app/open-with-web?file_id=ZmlsZTppZAo=' - -curl -X POST 'https://ocis.test/app/open-with-web?file_id=ZmlsZTppZAo=&app_name=Collabora' -``` - -**Response examples**: - -The URI from the response JSON is intended to be opened with a GET request in a browser. If the user has not yet a session in the browser, a login flow is handled by ownCloud Web. - -HTTP status code: 200 - -```json -{ - "uri": "https://....." -} -``` - -**Example responses (error case)**: - -See error cases for [Open a file with the app provider](#open-a-file-with-the-app-provider) - -### Open a File With the App Provider - -**Endpoint**: specified in the capabilities in `open_url`, currently `/app/open` - -**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**: - -- `file_id` (mandatory): id of the file to be opened -- `app_name` (optional) - - default (not given): default app for mime type - - possible values depend on the app providers for a mimetype from the `/app/open` endpoint -- `view_mode` (optional) - - default (not given): highest possible view mode, depending on the file permissions - - possible values: - - `write`: user can edit and download in the opening app - - `read`: user can view and download from the opening app - - `view`: user can view in the opening app (download is not possible) -- `lang` (optional) - - default (not given): default language of the application (which might maybe use the browser language) - - possible value is any ISO 639-1 language code. Examples: - - de - - en - - es - - ... - -**Request examples**: - -```bash -curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=' - -curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&lang=de' - -curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora' - -curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&view_mode=read' - -curl -X POST 'https://ocis.test/app/open?file_id=ZmlsZTppZAo=&app_name=Collabora&view_mode=write' -``` - -**Response examples**: - -All apps are expected to be opened in an iframe and the response will give some parameters for that action. - -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://.....", - "method": "POST", - "form_parameters": { - "access_token": "eyJ0...", - "access_token_ttl": "1634300912000", - "arbitrary_param": "lorem-ipsum" - } -} -``` - -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://...", - "method": "GET", - "headers": { - "access_token": "eyJ0e...", - "access_token_ttl": "1634300912000", - "arbitrary_header": "lorem-ipsum" - } -} -``` - -**Example responses (error case)**: - -- missing `file_id` - - HTTP status code: 400 - - ```json - { - "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": "RESOURCE_NOT_FOUND", - "message": "error: not found: app 'Collabora' not found" - } - ``` - -- wrong / invalid file id - - HTTP status code: 400 - - ```json - { - "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" - } - ``` - -- invalid language code - - HTTP status code: 400 - - ```json - { - "code": "INVALID_PARAMETER", - "message": "lang parameter does not contain a valid ISO 639-1 language code" - } - ``` - -### 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**: - -- `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?parent_container_id=c2lkOmNpZAo=&filename=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)**: - -- missing `parent_container_id` - - HTTP status code: 400 - - ```json - { - "code": "INVALID_PARAMETER", - "message": "missing parent container ID" - } - ``` - -- missing `filename` - - HTTP status code: 400 - - ```json - { - "code": "INVALID_PARAMETER", - "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 (e.g. includes a path segment) - - HTTP status code: 400 - - ```json - { - "code": "INVALID_PARAMETER", - "message": "the filename must not contain a path segment" - } - ``` - -- file already exists - - HTTP status code: 403 - - ```json - { - "code": "RESOURCE_ALREADY_EXISTS", - "message": "the file already exists" - } - ``` -## Example Yaml Config -{{< include file="services/_includes/app-registry-config-example.yaml" language="yaml" >}} - -{{< include file="services/_includes/app-registry_configvars.md" >}} -