✨(api) add API route to fetch document content

[sylvinus]

This allows API users to fetch document content, enabling the use of Docs as a headless CMS for instance, or any kind of document processing, with /api/v1.0/documents/xyz/content/?content_format=html URLs.

Fixes #1206.

[StephanMeijer]

Overhead

Instead of using the "content" and "format" fields, you can use the Content-Type-header and the body of the request. This will have as effect:

• No overhead in JSON-encoding
• Aligning with the HTTP spec more
• No overhead in base64: CPU/memory but also network traffic (base64 also increases traffic with ~33% and JSON also increases payload size with a tiny bit)

This is in line with the existing convert-endpoint.

Utilizing the existing convert-endpoint

Instead of writing a new endpoint, you can rewrite the convert-endpoint to accept a Accept and Content-Type header.

e.g.

POST /convert

Content-Type: text/markdown
Accept: application/vnd.yjs.doc

# Heading

Some text

Would transform the markdown document into a YJs document (raw non-base64 encoded content).

e.g.

POST /convert

Content-Type: application/vnd.yjs.doc
Accept: text/html

<binary contents>

Would transform the YJs document (raw non-base64 encoded content) to HTML.

It'd then respond by:

Content-Type: text/html

<h1>Heading</h1><p>Some text</p>

Last but not least.

If you have any questions about this approach, feel free to schedule a call with me and/or ask @lunika to be in our secret Matrix room.

I also left some code style comments.

[sylvinus]

@StephanMeijer Thanks for the review! Your approach is more concise indeed and I implemented all your feedbacks I think.

[StephanMeijer]

Will give it a new review today or tomorrow!

[StephanMeijer]

@sylvinus Can I propose a different style of writing this tomorrow? Need some time to get behind my editor,.

[sylvinus]

@StephanMeijer feel free to push on the branch, frankly I don't care that much about the internals, I just badly need the API as a user ;)

[sylvinus]

@StephanMeijer hi! Any news on this? Thanks !!

[sylvinus]

I've deployed this to our instance and begun testing. One thing I've just realized is that we need to register custom blocks to the server-side editor so they are rendered properly as HTML or Markdown.

That seems to introduce a dependency from impress to the y-provider, that didn't exist yet. Or should we put custom blocks in a new, third package?

[sylvinus]

FYI, prior art with a route that generated markdown by parsing the yjs blob : 06c26a7

Curious to discuss the benefits of both approaches!