* @author Bjoern Schiessle <bjoern@schiessle.org>
* @author Christoph Wurst <christoph@winzerhof-wurst.at>
* @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
*
* @license GNU AGPL version 3 or any later version
*
namespace OCA\CloudFederationAPI\Controller;
use OCA\CloudFederationAPI\Config;
+use OCA\CloudFederationAPI\ResponseDefinitions;
use OCP\AppFramework\Controller;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\JSONResponse;
use Psr\Log\LoggerInterface;
/**
- * Class RequestHandlerController
- *
- * handle API between different Cloud instances
+ * Open-Cloud-Mesh-API
*
* @package OCA\CloudFederationAPI\Controller
+ *
+ * @psalm-import-type CloudFederationApiAddShare from ResponseDefinitions
+ * @psalm-import-type CloudFederationApiValidationError from ResponseDefinitions
+ * @psalm-import-type CloudFederationApiError from ResponseDefinitions
*/
class RequestHandlerController extends Controller {
}
/**
- * add share
+ * Add share
*
* @NoCSRFRequired
* @PublicPage
* @BruteForceProtection(action=receiveFederatedShare)
*
- * @param string $shareWith
- * @param string $name resource name (e.g. document.odt)
- * @param string $description share description (optional)
- * @param string $providerId resource UID on the provider side
- * @param string $owner provider specific UID of the user who owns the resource
- * @param string $ownerDisplayName display name of the user who shared the item
- * @param string $sharedBy provider specific UID of the user who shared the resource
- * @param string $sharedByDisplayName display name of the user who shared the resource
- * @param array $protocol (e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]])
- * @param string $shareType ('group' or 'user' share)
- * @param $resourceType ('file', 'calendar',...)
- * @return Http\DataResponse|JSONResponse
+ * @param string $shareWith The user who the share will be shared with
+ * @param string $name The resource name (e.g. document.odt)
+ * @param string|null $description Share description
+ * @param string $providerId Resource UID on the provider side
+ * @param string $owner Provider specific UID of the user who owns the resource
+ * @param string|null $ownerDisplayName Display name of the user who shared the item
+ * @param string|null $sharedBy Provider specific UID of the user who shared the resource
+ * @param string|null $sharedByDisplayName Display name of the user who shared the resource
+ * @param array{name: string[], options: array<string, mixed>} $protocol e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]]
+ * @param string $shareType 'group' or 'user' share
+ * @param string $resourceType 'file', 'calendar',...
*
- * Example: curl -H "Content-Type: application/json" -X POST -d '{"shareWith":"admin1@serve1","name":"welcome server2.txt","description":"desc","providerId":"2","owner":"admin2@http://localhost/server2","ownerDisplayName":"admin2 display","shareType":"user","resourceType":"file","protocol":{"name":"webdav","options":{"sharedSecret":"secret","permissions":"webdav-property"}}}' http://localhost/server/index.php/ocm/shares
+ * @return JSONResponse<Http::STATUS_CREATED, CloudFederationApiAddShare, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, CloudFederationApiValidationError, array{}>|JSONResponse<Http::STATUS_NOT_IMPLEMENTED, CloudFederationApiError, array{}>
+ * 201: The notification was successfully received. The display name of the recipient might be returned in the body
+ * 400: Bad request due to invalid parameters, e.g. when `shareWith` is not found or required properties are missing
+ * 501: Share type or the resource type is not supported
*/
public function addShare($shareWith, $name, $description, $providerId, $owner, $ownerDisplayName, $sharedBy, $sharedByDisplayName, $protocol, $shareType, $resourceType) {
}
/**
- * receive notification about existing share
+ * Send a notification about an existing share
*
* @NoCSRFRequired
* @PublicPage
* @BruteForceProtection(action=receiveFederatedShareNotification)
*
- * @param string $notificationType (notification type, e.g. SHARE_ACCEPTED)
- * @param string $resourceType (calendar, file, contact,...)
- * @param string $providerId id of the share
- * @param array $notification the actual payload of the notification
- * @return JSONResponse
+ * @param string $notificationType Notification type, e.g. SHARE_ACCEPTED
+ * @param string $resourceType calendar, file, contact,...
+ * @param string|null $providerId ID of the share
+ * @param array<string, mixed>|null $notification The actual payload of the notification
+ *
+ * @return JSONResponse<Http::STATUS_CREATED, array<string, mixed>, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, CloudFederationApiValidationError, array{}>|JSONResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_IMPLEMENTED, CloudFederationApiError, array{}>
+ * 201: The notification was successfully received
+ * 400: Bad request due to invalid parameters, e.g. when `type` is invalid or missing
+ * 403: Getting resource is not allowed
+ * 501: The resource type is not supported
*/
- public function receiveNotification($notificationType, $resourceType, $providerId, array $notification) {
+ public function receiveNotification($notificationType, $resourceType, $providerId, ?array $notification) {
// check if all required parameters are set
if ($notificationType === null ||
--- /dev/null
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCA\CloudFederationAPI;
+
+/**
+ * @psalm-type CloudFederationApiAddShare = array{
+ * recipientDisplayName: string,
+ * }
+ *
+ * @psalm-type CloudFederationApiError = array{
+ * message: string,
+ * }
+ *
+ * @psalm-type CloudFederationApiValidationError = CloudFederationApiError&array{
+ * validationErrors: array{
+ * name: string,
+ * message: string|null,
+ * }[],
+ * }
+ */
+class ResponseDefinitions {
+}
projects / nextcloud-server.git / commitdiff