Merge pull request #1600 from oli-ver/feature/noid/stableAttachmentId

newhinton: Expose image api for other clients as api v1.4 including routes fix

Author: enjeck

appinfo/routes.php

@@ -183,15 +183,7 @@
 		'url' => '/api/{apiVersion}/settings',
 		'verb' => 'GET',
 		'requirements' => [
-			'apiVersion' => '(v1)',
-		],
-	],
-	[
-		'name' => 'notes_api#fail',
-		'url' => '/api/{catchAll}',
-		'verb' => 'GET',
-		'requirements' => [
-			'catchAll' => '.*',
+			'apiVersion' => '(v1|v1.4)',
 		],
 	],
 	[
@@ -203,4 +195,30 @@
 			'path' => '.+',
 		],
 	],
+	[
+		'name' => 'notes_api#getAttachment',
+		'url' => '/api/{apiVersion}/attachment/{noteid}',
+		'verb' => 'GET',
+		'requirements' => [
+			'apiVersion' => '(v1.4)',
+			'noteid' => '\d+'
+		],
+	],
+	[
+		'name' => 'notes_api#uploadFile',
+		'url' => '/api/{apiVersion}/attachment/{noteid}',
+		'verb' => 'POST',
+		'requirements' => [
+			'apiVersion' => '(v1.4)',
+			'noteid' => '\d+'
+		],
+	],
+	[
+		'name' => 'notes_api#fail',
+		'url' => '/api/{catchAll}',
+		'verb' => 'GET',
+		'requirements' => [
+			'catchAll' => '.*',
+		],
+	],
 ]];

docs/api/v1.md

@@ -9,12 +9,13 @@ In this document, the Notes API major version 1 and all its minor versions are d
 
 ## Minor versions
 
-| API version | Introduced with app version | Remarkable Changes |
-|:-----------:|:----------------------------|:-------------------|
-|  **1.0**    | Notes 3.3 (May 2020)        | Separate title, no auto rename based on content |
-|  **1.1**    | Notes 3.4 (May 2020)        | Filter "Get all notes" by category |
-|  **1.2**    | Notes 4.1 (June 2021)       | Preventing lost updates, read-only notes, settings |
-|  **1.3**    | Notes 4.5 (August 2022)     | Allow custom file suffixes |
+| API version | Introduced with app version | Remarkable Changes                                 |
+|:-----------:|:----------------------------|:---------------------------------------------------|
+|   **1.0**   | Notes 3.3 (May 2020)        | Separate title, no auto rename based on content    |
+|   **1.1**   | Notes 3.4 (May 2020)        | Filter "Get all notes" by category                 |
+|   **1.2**   | Notes 4.1 (June 2021)       | Preventing lost updates, read-only notes, settings |
+|   **1.3**   | Notes 4.5 (August 2022)     | Allow custom file suffixes                         |
+|   **1.4**   | Notes 4.9 (August 2025)     | Add external image api                             |
 
 
 
@@ -136,7 +137,7 @@ Note not found.
 <details><summary>Details</summary>
 
 #### Request parameters
-- **Body**: some or all "read/write" attributes (see section [Note attributes](#note-attributes)), example: 
+- **Body**: some or all "read/write" attributes (see section [Note attributes](#note-attributes)), example:
 ```js
 {
     "title": "New note",
@@ -278,6 +279,74 @@ No valid authentication credentials supplied.
 
 
 
+### Get attachment (`GET /attachment/{id}`)
+<details><summary>Details</summary>
+
+*(since API v1.4)*
+
+#### Request parameters
+| Parameter | Type                         | Description                                |
+|:----------|:-----------------------------|:-------------------------------------------|
+| `id`      | integer, required (path)     | ID of the note to load the attachment from |
+| `path`    | string, required (request)   | Path or name of the attachment to load.    |
+
+Example:
+
+```bash
+curl -u "user:password" "https://yournextcloud.com/index.php/apps/notes/api/v1.4/attachment/<id>?path=<path>" -o <outputfilename>.jpg
+```
+
+
+#### Response
+##### 200 OK
+- **Body**: Image or File
+
+##### 400 Bad Request
+Endpoint not supported by installed notes app version (requires API version 1.4).
+
+##### 401 Unauthorized
+No valid authentication credentials supplied.
+</details>
+
+
+### Put attachment (`POST /attachment/{id}`)
+<details><summary>Details</summary>
+
+*(since API v1.4)*
+
+#### Request parameters
+| Parameter | Type                    | Description                                     |
+|:----------|:------------------------|:------------------------------------------------|
+| `id`      | integer, required (path)| ID of the note to upload the attachment to      |
+
+Example:
+
+```bash
+curl -u "user:password" \
+       -X POST \
+       -F "file=@/path/to/image.png" \
+       "https://yournextcloud.com/index.php/apps/notes/api/v1.4/attachment/<id>"
+
+# The post request will return the filename that was generated:
+{"filename":"d8aef2005b4f815fec8ade5388240f2c.png"}
+```
+
+#### Response
+##### 200 OK
+- **Body**: Filename in json encoded:
+```js
+{
+    "filename": "image.jpg"
+}
+```
+
+##### 400 Bad Request
+Endpoint not supported by installed notes app version (requires API version 1.4).
+
+##### 401 Unauthorized
+No valid authentication credentials supplied.
+</details>
+
 ## Preventing lost updates and conflict solution
 
 While changing a note using a Notes client, the same note may be changed by another client.

lib/AppInfo/Application.php

@@ -21,7 +21,7 @@
 
 class Application extends App implements IBootstrap {
 	public const APP_ID = 'notes';
-	public static array $API_VERSIONS = [ '0.2', '1.3' ];
+	public static array $API_VERSIONS = [ '0.2', '1.3', '1.4' ];
 
 	public function __construct(array $urlParams = []) {
 		parent::__construct(self::APP_ID, $urlParams);

lib/Controller/NotesApiController.php

@@ -18,13 +18,16 @@
 use OCP\AppFramework\ApiController;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\JSONResponse;
+use OCP\AppFramework\Http\StreamResponse;
+use OCP\Files\IMimeTypeDetector;
 use OCP\IRequest;
 
 class NotesApiController extends ApiController {
 	private NotesService $service;
 	private MetaService $metaService;
 	private SettingsService $settingsService;
 	private Helper $helper;
+	private IMimeTypeDetector $mimeTypeDetector;
 
 	public function __construct(
 		string $AppName,
@@ -33,12 +36,14 @@ public function __construct(
 		MetaService $metaService,
 		SettingsService $settingsService,
 		Helper $helper,
+		IMimeTypeDetector $mimeTypeDetector,
 	) {
 		parent::__construct($AppName, $request);
 		$this->service = $service;
 		$this->metaService = $metaService;
 		$this->settingsService = $settingsService;
 		$this->helper = $helper;
+		$this->mimeTypeDetector = $mimeTypeDetector;
 	}
 
 
@@ -259,4 +264,52 @@ public function fail() : JSONResponse {
 			return new JSONResponse([], Http::STATUS_BAD_REQUEST);
 		});
 	}
+
+
+
+	/**
+	 * With help from: https://github.com/nextcloud/cookbook
+	 * @NoAdminRequired
+	 * @CORS
+	 * @NoCSRFRequired
+	 * @return JSONResponse|StreamResponse
+	 */
+	public function getAttachment(int $noteid, string $path): Http\Response {
+		try {
+			$targetimage = $this->service->getAttachment(
+				$this->helper->getUID(),
+				$noteid,
+				$path
+			);
+			$fileHandle = $targetimage->fopen('rb');
+			if ($fileHandle === false) {
+				throw new \Exception('Could not open file');
+			}
+			$response = new StreamResponse($fileHandle);
+			$response->addHeader('Content-Disposition', 'attachment; filename="' . rawurldecode($targetimage->getName()) . '"');
+			$response->addHeader('Content-Type', $this->mimeTypeDetector->getSecureMimeType($targetimage->getMimeType()));
+			$response->addHeader('Cache-Control', 'public, max-age=604800');
+			return $response;
+		} catch (\Exception $e) {
+			$this->helper->logException($e);
+			return $this->helper->createErrorResponse($e, Http::STATUS_NOT_FOUND);
+		}
+	}
+
+	/**
+	 * @NoAdminRequired
+	 * @CORS
+	 * @NoCSRFRequired
+	 */
+	public function uploadFile(int $noteid): JSONResponse {
+		$file = $this->request->getUploadedFile('file');
+		return $this->helper->handleErrorResponse(function () use ($noteid, $file): array {
+			return $this->service->createImage(
+				$this->helper->getUID(),
+				$noteid,
+				$file
+			);
+		});
+	}
+
 }