Merge pull request #46378 from nextcloud/feat/public_reference_api

feat(Reference): Add public API endpoints to get references
nextcloud · Jul 17, 2024 · e4368f6 · e4368f6
2 parents b06ce83 + 1671bf3
commit e4368f6
Show file tree

Hide file tree

Showing 9 changed files with 794 additions and 14 deletions.
diff --git a/core/Controller/ReferenceApiController.php b/core/Controller/ReferenceApiController.php
@@ -10,6 +10,7 @@
 
 use OC\Core\ResponseDefinitions;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\AnonRateLimit;
 use OCP\AppFramework\Http\Attribute\ApiRoute;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Collaboration\Reference\IDiscoverableReferenceProvider;
@@ -22,6 +23,8 @@
  * @psalm-import-type CoreReferenceProvider from ResponseDefinitions
  */
 class ReferenceApiController extends \OCP\AppFramework\OCSController {
+	private const LIMIT_MAX = 15;
+
 	public function __construct(
 		string $appName,
 		IRequest $request,
@@ -62,6 +65,39 @@ public function extract(string $text, bool $resolve = false, int $limit = 1): Da
 		]);
 	}
 
+	/**
+	 * @PublicPage
+	 *
+	 * Extract references from a text
+	 *
+	 * @param string $text Text to extract from
+	 * @param string $sharingToken Token of the public share
+	 * @param bool $resolve Resolve the references
+	 * @param int $limit Maximum amount of references to extract, limited to 15
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
+	 *
+	 * 200: References returned
+	 */
+	#[ApiRoute(verb: 'POST', url: '/extractPublic', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
+	public function extractPublic(string $text, string $sharingToken, bool $resolve = false, int $limit = 1): DataResponse {
+		$references = $this->referenceManager->extractReferences($text);
+
+		$result = [];
+		$index = 0;
+		foreach ($references as $reference) {
+			if ($index++ >= min($limit, self::LIMIT_MAX)) {
+				break;
+			}
+
+			$result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference, true, $sharingToken)?->jsonSerialize() : null;
+		}
+
+		return new DataResponse([
+			'references' => $result
+		]);
+	}
+
 	/**
 	 * @NoAdminRequired
 	 *
@@ -73,6 +109,7 @@ public function extract(string $text, bool $resolve = false, int $limit = 1): Da
 	 * 200: Reference returned
 	 */
 	#[ApiRoute(verb: 'GET', url: '/resolve', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
 	public function resolveOne(string $reference): DataResponse {
 		/** @var ?CoreReference $resolvedReference */
 		$resolvedReference = $this->referenceManager->resolveReference(trim($reference))?->jsonSerialize();
@@ -82,6 +119,28 @@ public function resolveOne(string $reference): DataResponse {
 		return $response;
 	}
 
+	/**
+	 * @PublicPage
+	 *
+	 * Resolve from a public page
+	 *
+	 * @param string $reference Reference to resolve
+	 * @param string $sharingToken Token of the public share
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, ?CoreReference>}, array{}>
+	 *
+	 * 200: Reference returned
+	 */
+	#[ApiRoute(verb: 'GET', url: '/resolvePublic', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
+	public function resolveOnePublic(string $reference, string $sharingToken): DataResponse {
+		/** @var ?CoreReference $resolvedReference */
+		$resolvedReference = $this->referenceManager->resolveReference(trim($reference), true, trim($sharingToken))?->jsonSerialize();
+
+		$response = new DataResponse(['references' => [$reference => $resolvedReference]]);
+		$response->cacheFor(3600, false, true);
+		return $response;
+	}
+
 	/**
 	 * @NoAdminRequired
 	 *
@@ -110,6 +169,36 @@ public function resolve(array $references, int $limit = 1): DataResponse {
 		]);
 	}
 
+	/**
+	 * @PublicPage
+	 *
+	 * Resolve multiple references from a public page
+	 *
+	 * @param string[] $references References to resolve
+	 * @param string $sharingToken Token of the public share
+	 * @param int $limit Maximum amount of references to resolve, limited to 15
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
+	 *
+	 * 200: References returned
+	 */
+	#[ApiRoute(verb: 'POST', url: '/resolvePublic', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
+	public function resolvePublic(array $references, string $sharingToken, int $limit = 1): DataResponse {
+		$result = [];
+		$index = 0;
+		foreach ($references as $reference) {
+			if ($index++ >= min($limit, self::LIMIT_MAX)) {
+				break;
+			}
+
+			$result[$reference] = $this->referenceManager->resolveReference($reference, true, $sharingToken)?->jsonSerialize();
+		}
+
+		return new DataResponse([
+			'references' => $result
+		]);
+	}
+
 	/**
 	 * @NoAdminRequired
 	 *