Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
docs(etapi): document binary uploads to note and attachment content
Elian Doran9727399afd50
diff --git a/apps/server/spec/etapi/attachment-content.spec.ts b/apps/server/spec/etapi/attachment-content.spec.tsindex 5fc9e41657..6cf3ca1076 100644--- a/apps/server/spec/etapi/attachment-content.spec.ts+++ b/apps/server/spec/etapi/attachment-content.spec.ts@@ -53,14 +53,36 @@ describe("etapi/attachment-content", () => {expect(response.text).toStrictEqual(text);});- it("supports binary content", async() => {+ it("stores binary content uploaded to an attachment created without content", async() => {+ const created = await supertest(app)+ .post(`/etapi/attachments`)+ .auth(USER, token, { "type": "basic"})+ .send({+ "ownerId": createdNoteId,+ "role": "image",+ "mime": "image/png",+ "title": "image.png",+ "position": 10+ })+ .expect(201);+ const attachmentId = created.body.attachmentId;++ // Bytes that are not valid UTF-8, so a text round trip would corrupt them.+ const bytes = Buffer.from([ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff, 0xfe, 0x80 ]);await supertest(app)- .put(`/etapi/attachments/${createdAttachmentId}/content`)+ .put(`/etapi/attachments/${attachmentId}/content`).auth(USER, token, { "type": "basic"}).set("Content-Type", "application/octet-stream")- .set("Content-Transfer-Encoding", "binary")- .send(Buffer.from("Hello world"))+ .send(bytes).expect(204);++ const response = await supertest(app)+ .get(`/etapi/attachments/${attachmentId}/content`)+ .auth(USER, token, { "type": "basic"})+ .responseType("blob")+ .expect(200)+ .expect("Content-Type", "image/png");+ expect(Buffer.compare(response.body, bytes)).toBe(0);});it("refuses to read and write a protected attachment's content", async () => {diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).htmlindex 3a3c2fdf84..8454c5f4e7 100644--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).html+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/ETAPI (REST API).html@@ -53,4 +53,24 @@ curl "$SERVER/etapi/notes/$NOTE_ID/content" -H "Authorization: $TOKEN" </code></a directory called <code>out</code>, simply replace the last statement inthe script with:</p><pre><code class="language-text-x-trilium-auto">curl -H "Authorization: $TOKEN" \-X GET "$SERVER/etapi/notes/$NOTE_ID/export" \- --output "out/$NOTE_ID.zip"</code></pre>\ No newline at end of file+ --output "out/$NOTE_ID.zip"</code></pre>+<h2>Uploading binary content</h2>+<p>A JSON request body can only carry text, so the <code>content</code> field+ of <code>POST /etapi/attachments</code> stores exactly the string it receives.+ To upload an image, a PDF or any other binary file, send the raw bytes+ to the content endpoint with the <code>application/octet-stream</code> content+ type. The same applies to the content of a note (<code>PUT /etapi/notes/{noteId}/content</code>).</p>+<p>To attach a file to a note, create the attachment without content, then+ upload the file to it:</p><pre><code class="language-text-x-trilium-auto">ATTACHMENT_ID=$(curl -s -X POST "$SERVER/etapi/attachments" \+ -H "Authorization: $TOKEN" \+ -H "Content-Type: application/json" \+ -d "{\"ownerId\": \"$NOTE_ID\", \"role\": \"file\", \"mime\": \"application/pdf\", \"title\": \"report.pdf\", \"position\": 10}" \+ | jq -r .attachmentId)++curl -X PUT "$SERVER/etapi/attachments/$ATTACHMENT_ID/content" \+ -H "Authorization: $TOKEN" \+ -H "Content-Type: application/octet-stream" \+ --data-binary @report.pdf</code></pre>+<p>Use <code>--data-binary</code> rather than <code>-d</code>, which strips+ line breaks from the file. For an image, set <code>role</code> to <code>image</code> and <code>mime</code> to+ the image's type, such as <code>image/png</code>.</p>\ No newline at end of filediff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.htmlindex 50931fe8f9..8b724fa0e2 100644--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.html+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/Notes/Printing & Exporting as PDF.html@@ -116,9 +116,9 @@href="#root/_help_4TIF1oA4VQRO">Options</a> and assigning a key combinationfor:</p><ul>- <li class="ck-list-marker-italic"><em>Print Active Note</em>+ <li><em>Print Active Note</em></li>- <li class="ck-list-marker-italic"><em>Export Active Note as PDF</em>+ <li><em>Export Active Note as PDF</em></li></ul><h2>Constraints & limitations</h2>diff --git a/apps/server/src/assets/etapi.openapi.yaml b/apps/server/src/assets/etapi.openapi.yamlindex a0234c0f0a..35d77d9163 100644--- a/apps/server/src/assets/etapi.openapi.yaml+++ b/apps/server/src/assets/etapi.openapi.yaml@@ -236,21 +236,29 @@ paths:operationId: getNoteContentresponses:"200":- description: note content response+ description: note content, served with the note's MIME type as `Content-Type`content:- text/html:+ "*/*":schema:type: string+ format: binaryput:description: Updates note content identified by its IDoperationId: putNoteContentByIdrequestBody:- description: html content of note+ description: >+ New content of the note. Send text (such as the HTML of a text note) as+ `text/plain` and binary data (such as the file of an image or file note) as+ `application/octet-stream`; other content types are not accepted.required: truecontent:text/plain:schema:type: string+ application/octet-stream:+ schema:+ type: string+ format: binaryresponses:"204":description: note content updated@@ -671,21 +679,29 @@ paths:operationId: getAttachmentContentresponses:"200":- description: attachment content response+ description: attachment content, served with the attachment's MIME type as `Content-Type`content:- text/html:+ "*/*":schema:type: string+ format: binaryput:description: Updates attachment content identified by its IDoperationId: putAttachmentContentByIdrequestBody:- description: html content of attachment+ description: >+ New content of the attachment. Send text as `text/plain` and binary data+ (such as an image or a PDF) as `application/octet-stream`; other content+ types are not accepted.required: truecontent:text/plain:schema:type: string+ application/octet-stream:+ schema:+ type: string+ format: binaryresponses:"204":description: attachment content updated@@ -1296,6 +1312,10 @@ components:type: stringcontent:type: string+ description: >+ Text content of the attachment, stored as-is. To store binary content,+ create the attachment without it, then upload the data with+ `PUT /attachments/{attachmentId}/content`.position:type: integerformat: int32diff --git a/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md b/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).mdindex c50694b731..869d7984dd 100644--- a/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md+++ b/docs/User Guide/User Guide/Advanced Usage/ETAPI (REST API).md@@ -70,4 +70,25 @@ As another example, to obtain a .zip export of a note and place it in a directorcurl -H "Authorization: $TOKEN" \-X GET "$SERVER/etapi/notes/$NOTE_ID/export" \--output "out/$NOTE_ID.zip"-```\ No newline at end of file+```++## Uploading binary content++A JSON request body can only carry text, so the `content` field of `POST /etapi/attachments` stores exactly the string it receives. To upload an image, a PDF or any other binary file, send the raw bytes to the content endpoint with the `application/octet-stream` content type. The same applies to the content of a note (`PUT /etapi/notes/{noteId}/content`).++To attach a file to a note, create the attachment without content, then upload the file to it:++```+ATTACHMENT_ID=$(curl -s -X POST "$SERVER/etapi/attachments" \+ -H "Authorization: $TOKEN" \+ -H "Content-Type: application/json" \+ -d "{\"ownerId\": \"$NOTE_ID\", \"role\": \"file\", \"mime\": \"application/pdf\", \"title\": \"report.pdf\", \"position\": 10}" \+ | jq -r .attachmentId)++curl -X PUT "$SERVER/etapi/attachments/$ATTACHMENT_ID/content" \+ -H "Authorization: $TOKEN" \+ -H "Content-Type: application/octet-stream" \+ --data-binary @report.pdf+```++Use `--data-binary` rather than `-d`, which strips line breaks from the file. For an image, set `role` to `image` and `mime` to the image's type, such as `image/png`.\ No newline at end of file