Direct editing API to allow file editing using a one-time token

[juliushaertl]

Early draft PR so @tobiasKaminsky has something to play with 😉

The idea is to unify the token generation and endpoints into a server API, so mobile apps and the desktop client can just query one endpoint instead of requiring individual implementation for every app. The basic concept is that mobile apps now can request a one time url to edit a file, which can be opened in an unauthenticated webview by the apps.

Editor class

This class defines how your app is presented in the frontend (name), which filetypes it can handle as well as the endpoint that will be shown when the one-time link is opened. Inside of the open method you can then just load the onlyoffice editor with the file that is provided in the $token parameter.
https://github.com/nextcloud/text/blob/db42744a5c651666ca91d66219f77ae5775f949c/lib/DirectEditing/TextDirectEditor.php

Register the editor class in your lib/AppInfo/Application.php

/** @var IEventDispatcher $eventDispatcher */
$eventDispatcher->addListener(RegisterDirectEditorEvent::class, function (RegisterDirectEditorEvent $event) use ($container) {
	$editor = $container->query(TextDirectEditor::class);
	$event->register($editor);
});

Add document creators:

Creators are used to show entries in the mobile apps like "Create a new
spreadsheet" Furthermore you can also prefill the file with some content
if that is needed for the specific mimetype. Once you have added a class
it also needs to be registered in your Editor class.
https://github.com/nextcloud/text/blob/db42744a5c651666ca91d66219f77ae5775f949c/lib/DirectEditing/TextDocumentCreator.php

API endpoints

Obtain editor details

curl 'https://admin:[email protected]/ocs/v2.php/apps/files/api/v1/directEditing?format=json' -H 'OCS-APIRequest: true'

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "editors": {
        "text": {
          "name": "Nextcloud Text",
          "mimetypes": [
            "text/markdown"
          ],
          "optionalMimetypes": [
            "text/plain"
          ],
          "secure": false
        }
      },
      "creators": {
        "textdocument": {
          "id": "textdocument",
          "name": "New text document",
          "extension": ".md",
          "templates": false
        },
        "textdocumenttemplate": {
          "id": "textdocumenttemplate",
          "name": "New text document from template",
          "extension": ".md",
          "templates": true
        }
      }
    }
  }
}

Get the list of templates

curl 'https://admin:[email protected]/ocs/v2.php/apps/files/api/v1/directEditing/templates/text/textdocumenttemplate?format=json' -H 'OCS-APIRequest: true'

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "1": {
        "id": "1",
        "extension": "md",
        "name": "Weekly ToDo",
        "preview": "https://cloud.bitgrid.net/apps/richdocuments/template/preview/832537"
      },
      "2": {
        "id": "2",
        "extension": "md",
        "name": "Meeting notes",
        "preview": "https://cloud.bitgrid.net/apps/richdocuments/template/preview/832537"
      }
    }
  }
}

Create an empty file

curl -X POST 'https://admin:[email protected]/ocs/v2.php/apps/files/api/v1/directEditing/create?path=/foo1.md&editorId=text&creatorId=textdocument&format=json' -H 'OCS-APIRequest: true'

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "url": "https://nextcloud.local/index.php/apps/files/directEditing/DbAy3rzfdBosKJjtQyxjq5s9Wz5MAZsjf9cHRZ4LKALrjnawxRAXzncNRpbzYEbT"
    }
  }
}

Create a file from a template

curl -X POST 'https://admin:[email protected]/ocs/v2.php/apps/files/api/v1/directEditing/create?path=/foo1.md&editorId=text&creatorId=textdocumenttemplate&templateId=1&format=json' -H 'OCS-APIRequest: true'

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "url": "https://nextcloud.local/index.php/apps/files/directEditing/DbAy3rzfdBosKJjtQyxjq5s9Wz5MAZsjf9cHRZ4LKALrjnawxRAXzncNRpbzYEbT"
    }
  }
}

Open a file

curl -X POST 'https://admin:[email protected]/ocs/v2.php/apps/files/api/v1/directEditing/open?path=/subfolder/123.txt&editorId=text&format=json' -H 'OCS-APIRequest: true'

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": {
      "url": "https://nextcloud.local/index.php/apps/files/directEditing/DbAy3rzfdBosKJjtQyxjq5s9Wz5MAZsjf9cHRZ4LKALrjnawxRAXzncNRpbzYEbT"
    }
  }
}

[tobiasKaminsky]

❗ I also rebased

[juliushaertl]

Ready for a first round of review, I'll look into adding some tests

[ChristophWurst]

Looks nice otherwise :)

[ChristophWurst]

Just a few nitpicks. The rest looks great!

[juliushaertl]

After discussing with @tobiasKaminsky I moved the editor details to the files app capabilities as this will save us one additional request on the apps and will have a rather minimal performance impact on the server side, since most of the data should be static and coming from hardcoded values in php classes.

[ChristophWurst]

Looks great!

[rullzer]

Lets do this then!

[tobiasKaminsky]

Is this documentation somewhere available?

[rullzer]

Nope. @juliushaertl be sure to add it to the docs indeed

[marinofaggiana]

Please update and verify the document: "API endpoints" because it's incorrect. thanks

[marinofaggiana]

@juliushaertl the "Get the list of templates" if do not exists a templates do not return nothing, but the Richdocuments API return one record with template of name "Empty", can we use the same logic ?