Introduce Server-side editor API docs

[DawidKossowski]

Suggested merge commit message (convention)

Docs: Introduce Server-side editor API docs.

---

Additional information

Do NOT merge it before CS releases the feature.

[scofalik]

Some final improvements, I'll add them myself using GH UI.

[Reinmar]

Just an idea – any chance for a simple system diagram that shows e.g. a scene like this (naming of things should probably be improved a bit):

graph TD
    %% User A and B
    subgraph Browser_A["Browser (user A)"]
        A1["Editor instance (user A)"]
    end

    subgraph Browser_B["Browser (user B)"]
        B1["Editor instance (user B)"]
    end

    %% Cloud Services
    subgraph Cloud["Cloud Services"]
        C1["Editor instance (virtual user)"]
        CS["Collaboration Server"]
    end

    %% Application Backend
    Backend["Application backend (your system)"]

    %% Connections
    A1 --> CS
    B1 --> CS
    C1 --> CS
    Backend -->|Server-side Editor API| C1

Loading

[Reinmar]

Ideally, we should have a short example here, so all the necessary knowledge is in one place. At least from the API usage perspective – so assuming that someone uploaded a bundle and have credentials already. Something that will be sufficient for a person familiar with the Collab REST APIs already.

Alternatively/Optionally: This could be a screencast showing one of the usecases: E.g. adding a comment via SS Ed API, while it simultaneously shows up in the editor content in a browser.

[Reinmar]

Note: This screencast will be useful for the blog post as well (cc @wojtekidd)

[Reinmar]

For example, one completely unclear thing here is – how I choose which document will the SS Ed API apply? What do I need to do to set that up? What if there's a collab session already? What if not?

I suppose details of this will make sense in the CS guide, but some minor explanation here and practical example may help a lot.

[Witoso]

could be useful questions to answer @godai78

[godai78]

We'll get to it, I believe :)

[Witoso]

yeah, the tricky part will be how much to add to this guide to understand enough without the need to jump around.

[Witoso]

Great guide, I really like it. I have one problem, imagining the total noob users, like me, I couldn't answer the question from where should I get the editor instance in all of those cases.

[Reinmar]

I actually know that bit from the demo that we had on All Hands :D But yeah – that's exactly the reason why we need a practical example.

Second part that's unknown: how to read (and that you can actually pass) params from the REST endpoint.

[scofalik]

Yes, editor is a globally available variable, I think it could be mentioned just before the very first snippet. And we should also mention that you can simply copy-paste these snippets as payload for the REST API endpoint.

But one more missing piece of data may be that you actually need to upload the bundle. Of course that will be in the CS guide, but would be good to have it here as well?

Thanks for comments, we are biased with having this knowledge.

[godai78]

You do realize this is not exactly a guide for total noobs? We need to assume the user reading this has already gone through some of our docs, and also, I think we should link some to not duplicate all the knowledge. The question is the extent of this.

[Witoso]

I think even mediocre and advanced noobs will have no idea where the magic variable in 5+ snippets comes from and how to get it on the server ;)

[godai78]

Yeah, this one is true :D

[DawidKossowski]

I do not fully agree with those comments. The idea and the requirements were to prepare scripts that would inspire people and function correctly when copied&pasted -- and this has been fulfilled. No one will be able to use the SS Editor API without referring to the CS documentation, where detailed information should be provided.

However, if you feel that this information should be included here as well, we will add it.

[Witoso]

I only need a sentence or a callout (note) that editor is globally available, that's all :D.

[godai78]

It was added this morning :)

[Witoso]

It's not a fully correct sentence. editor is not globally available unless someone makes it. We enable in Cloud as such. We need an explicit mention that in Cloud env editor is available globally.

[godai78]

Like this?

[Witoso]

As this is relevant to all snippets (not just data). I propose to move this https://github.com/ckeditor/ckeditor5/pull/18641/files#r2152270879

[godai78]

Looks like the CS part has been merged: https://github.com/cksource/docs/pull/760

[jflakus-cksource]

Docs are available on prod: https://ckeditor.com/docs/cs/latest/guides/collaboration/server-side-editor-api.html

[Witoso]

Are we rebasing to release?

[godai78]

Are we rebasing to release?

No real need to do that. We may merge it now, "as is," just as well. Unless we specifically want to ship it with the release for some reason.

[Witoso]

Please plan the merge of it 😊