Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add create document api endpoint #467

Merged
merged 2 commits into from
Dec 12, 2024

Conversation

sampaccoud
Copy link
Member

@sampaccoud sampaccoud commented Dec 1, 2024

Purpose

We want trusted external applications to be able to create documents via the API on behalf of any user.

Proposal

Add an action API endpoint limited to document creation and with a basic server-to-server authentication:
/api/v1.0/documents/create-for-user/

Expected payload:

{
    "title": "My document title",     # document title 
    "content": "My document content", # document content in ydoc format
    "sub": "123",                     # "sub" of the user in the remote application who may pre-exist in our db
    "email": "john.doe@example.com",  # email to send invitation in case the user "sub" doesn't exist in our db
    "language": "fr-fr",              # [optional] language in which the invitation email should be sent
    "message": "My custom message",   # [optional] custom message in the invitation email
    "subject": "My custom subject",   # [optional] custom subject for the invitation email
}

The user may or may not pre-exist in our database and should be notified of the document creation by email.

@sampaccoud sampaccoud force-pushed the add-create-document-api-endpoint branch from aabd704 to 97abaad Compare December 1, 2024 11:02
Copy link
Collaborator

@lebaudantoine lebaudantoine left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This endpoint breaks encapsulation by requiring external services to pass data in the highly specific Yjs format, which is tightly coupled to the Doc implementation. It impacts the usability of the endpoint.

Moreover, it should implement a robust validation to ensure the content value is well-formed and will not cause errors when opening the document.

Finally, allowing the conversion of Markdown strings into Yjs format, supporting broader use cases like importing or transforming existing documents, would be a really nice enhancement.

Some of these requirements depend on the ability to execute JavaScript code. This capability is expected to be available soon, once @AntoLC completes the upgrade to the collaboration service.

We agreed to merge my draft microservice into the collaboration one.

This endpoint may need to adapt its behavior based on the input format. Should we consider adding a parameter to explicitly specify the format?

This PR also introduces documents without any owner, which might need to be discussed.

I really need this endpoint ASAP. Should we merge it as proposed initially by @sampaccoud, and iterate with other PR?

@lebaudantoine lebaudantoine force-pushed the add-create-document-api-endpoint branch from df880a0 to 1efdabf Compare December 11, 2024 14:47
Copy link
Member Author

@sampaccoud sampaccoud left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All nitpicks. Move ahead!

@lebaudantoine lebaudantoine force-pushed the add-create-document-api-endpoint branch from 1efdabf to b260e12 Compare December 12, 2024 10:38
The email footer file is not being used and should be deleted.
@lebaudantoine lebaudantoine force-pushed the add-create-document-api-endpoint branch from b260e12 to 1d14395 Compare December 12, 2024 11:27
We want trusted external applications to be able to create documents
via the API on behalf of any user. The user may or may not pre-exist
in our database and should be notified of the document creation by
email.
@lebaudantoine lebaudantoine force-pushed the add-create-document-api-endpoint branch from 1d14395 to ee8e64c Compare December 12, 2024 11:32
@lebaudantoine lebaudantoine enabled auto-merge (rebase) December 12, 2024 12:14
@lebaudantoine lebaudantoine merged commit 5cdd06d into main Dec 12, 2024
15 of 16 checks passed
@lebaudantoine lebaudantoine deleted the add-create-document-api-endpoint branch December 12, 2024 13:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants