archive
/
nextcloud
mirror of https://github.com/nextcloud/server.git
1
0
Fork 0
Code Issues Releases Wiki Activity

federatedfilesharing: Add OpenAPI spec

Browse Source 
Signed-off-by: jld3103 <jld3103yt@gmail.com>
pull/39328/head
jld3103 12 months ago
parent 46284f1696
commit 4ead6e64a4
No known key found for this signature in database
GPG Key ID: 9062417B9E8EB7B3
6 changed files with 1021 additions and 58 deletions
Show Stats Download Patch File Download Diff File

2
apps/federatedfilesharing/lib/AddressHandler.php
Unescape Escape View File

@ -67,7 +67,7 @@ class AddressHandler {
* split user and remote from federated cloud id
*
* @param string $address federated share address
* @return array [user, remoteURL]
* @return array<string> [user, remoteURL]
* @throws HintException
*/
public function splitUserRemote($address) {

10
apps/federatedfilesharing/lib/Controller/MountPublicLinkController.php
Unescape Escape View File

@ -82,10 +82,12 @@ class MountPublicLinkController extends Controller {
* @PublicPage
* @BruteForceProtection(action=publicLink2FederatedShare)
*
* @param string $shareWith
* @param string $token
* @param string $password
* @return JSONResponse
* @param string $shareWith Username to share with
* @param string $token Token of the share
* @param string $password Password of the share
* @return JSONResponse<Http::STATUS_OK, array{remoteUrl: string}, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, array{message: string}, array{}>
* 200: Remote URL returned
* 400: Creating share is not possible
*/
public function createFederatedShare($shareWith, $token, $password = '') {
if (!$this->federatedShareProvider->isOutgoingServer2serverShareEnabled()) {

96
apps/federatedfilesharing/lib/Controller/RequestHandlerController.php
Unescape Escape View File

@ -123,16 +123,16 @@ class RequestHandlerController extends OCSController {
*
* create a new share
*
* @param string|null $remote
* @param string|null $token
* @param string|null $name
* @param string|null $owner
* @param string|null $sharedBy
* @param string|null $shareWith
* @param int|null $remoteId
* @param string|null $sharedByFederatedId
* @param string|null $ownerFederatedId
* @return Http\DataResponse
* @param string|null $remote Address of the remote
* @param string|null $token Shared secret between servers
* @param string|null $name Name of the shared resource
* @param string|null $owner Display name of the receiver
* @param string|null $sharedBy Display name of the sender
* @param string|null $shareWith ID of the user that receives the share
* @param int|null $remoteId ID of the remote
* @param string|null $sharedByFederatedId Federated ID of the sender
* @param string|null $ownerFederatedId Federated ID of the receiver
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function createShare(
@ -194,19 +194,19 @@ class RequestHandlerController extends OCSController {
*
* create re-share on behalf of another user
*
* @param int $id
* @param string|null $token
* @param string|null $shareWith
* @param int|null $permission
* @param int|null $remoteId
* @return Http\DataResponse
* @throws OCSBadRequestException
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @param string|null $shareWith ID of the user that receives the share
* @param int|null $remoteId ID of the remote
* @return Http\DataResponse<Http::STATUS_OK, array{token: string, remoteId: string}, array{}>
* @throws OCSBadRequestException Re-sharing is not possible
* @throws OCSException
*
* 200: Remote share returned
*/
public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $permission = 0, ?int $remoteId = 0) {
public function reShare(int $id, ?string $token = null, ?string $shareWith = null, ?int $remoteId = 0) {
if ($token === null ||
$shareWith === null ||
$permission === null ||
$remoteId === null
) {
throw new OCSBadRequestException();
@ -244,12 +244,14 @@ class RequestHandlerController extends OCSController {
*
* accept server-to-server share
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @param int $id ID of the remote share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
* @throws ShareNotFound
* @throws \OCP\HintException
*
* 200: Share accepted successfully
*/
public function acceptShare(int $id, ?string $token = null) {
$notification = [
@ -278,9 +280,9 @@ class RequestHandlerController extends OCSController {
*
* decline server-to-server share
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @param int $id ID of the remote share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function declineShare(int $id, ?string $token = null) {
@ -310,9 +312,9 @@ class RequestHandlerController extends OCSController {
*
* remove server-to-server share if it was unshared by the owner
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSException
*/
public function unshare(int $id, ?string $token = null) {
@ -345,10 +347,12 @@ class RequestHandlerController extends OCSController {
*
* federated share was revoked, either by the owner or the re-sharer
*
* @param int $id
* @param string|null $token
* @return Http\DataResponse
* @throws OCSBadRequestException
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSBadRequestException Revoking the share is not possible
*
* 200: Share revoked successfully
*/
public function revoke(int $id, ?string $token = null) {
try {
@ -385,11 +389,13 @@ class RequestHandlerController extends OCSController {
*
* update share information to keep federated re-shares in sync
*
* @param int $id
* @param string|null $token
* @param int|null $permissions
* @return Http\DataResponse
* @throws OCSBadRequestException
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @param int|null $permissions New permissions
* @return Http\DataResponse<Http::STATUS_OK, array<empty>, array{}>
* @throws OCSBadRequestException Updating permissions is not possible
*
* 200: Permissions updated successfully
*/
public function updatePermissions(int $id, ?string $token = null, ?int $permissions = null) {
$ncPermissions = $permissions;
@ -439,14 +445,14 @@ class RequestHandlerController extends OCSController {
*
* change the owner of a server-to-server share
*
* @param int $id
* @param string|null $token
* @param string|null $remote
* @param string|null $remote_id
* @return Http\DataResponse
* @throws OCSBadRequestException
* @throws OCSException
* @throws \OCP\DB\Exception
* @param int $id ID of the share
* @param string|null $token Shared secret between servers
* @param string|null $remote Address of the remote
* @param string|null $remote_id ID of the remote
* @return Http\DataResponse<Http::STATUS_OK, array{remote: string, owner: string}, array{}>
* @throws OCSBadRequestException Moving share is not possible
*
* 200: Share moved successfully
*/
public function move(int $id, ?string $token = null, ?string $remote = null, ?string $remote_id = null) {
if (!$this->isS2SEnabled()) {

14
apps/federatedfilesharing/lib/OCM/CloudFederationProviderFiles.php
Unescape Escape View File

@ -211,7 +211,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider {
* @param string $notificationType (e.g. SHARE_ACCEPTED)
* @param string $providerId id of the share
* @param array $notification payload of the notification
* @return array data send back to the sender
* @return array<string> data send back to the sender
*
* @throws ActionNotSupportedException
* @throws AuthenticationFailedException
@ -280,7 +280,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws ActionNotSupportedException
* @throws AuthenticationFailedException
* @throws BadRequestException
@ -348,7 +348,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws ActionNotSupportedException
* @throws AuthenticationFailedException
* @throws BadRequestException
@ -424,7 +424,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws AuthenticationFailedException
* @throws BadRequestException
*/
@ -446,7 +446,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws ActionNotSupportedException
* @throws BadRequestException
*/
@ -536,7 +536,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws AuthenticationFailedException
* @throws BadRequestException
* @throws ProviderCouldNotAddShareException
@ -597,7 +597,7 @@ class CloudFederationProviderFiles implements ICloudFederationProvider {
*
* @param string $id
* @param array $notification
* @return array
* @return array<string>
* @throws AuthenticationFailedException
* @throws BadRequestException
*/

955
apps/federatedfilesharing/openapi.json
Unescape Escape View File

@ -0,0 +1,955 @@
{
"openapi": "3.0.3",
"info": {
"title": "federatedfilesharing",
"version": "0.0.1",
"description": "Provide federated file sharing across servers",
"license": {
"name": "agpl"
}
},
"components": {
"securitySchemes": {
"basic_auth": {
"type": "http",
"scheme": "basic"
},
"bearer_auth": {
"type": "http",
"scheme": "bearer"
}
},
"schemas": {
"OCSMeta": {
"type": "object",
"required": [
"status",
"statuscode"
],
"properties": {
"status": {
"type": "string"
},
"statuscode": {
"type": "integer"
},
"message": {
"type": "string"
},
"totalitems": {
"type": "string"
},
"itemsperpage": {
"type": "string"
}
}
}
}
},
"paths": {
"/index.php/apps/federatedfilesharing/createFederatedShare": {
"post": {
"operationId": "mount_public_link-create-federated-share",
"summary": "send federated share to a user of a public link",
"tags": [
"mount_public_link"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "shareWith",
"in": "query",
"description": "Username to share with",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "token",
"in": "query",
"description": "Token of the share",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "password",
"in": "query",
"description": "Password of the share",
"schema": {
"type": "string",
"default": ""
}
}
],
"responses": {
"200": {
"description": "Remote URL returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"remoteUrl"
],
"properties": {
"remoteUrl": {
"type": "string"
}
}
}
}
}
},
"400": {
"description": "Creating share is not possible",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares": {
"post": {
"operationId": "request_handler-create-share",
"summary": "create a new share",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "remote",
"in": "query",
"description": "Address of the remote",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "name",
"in": "query",
"description": "Name of the shared resource",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "owner",
"in": "query",
"description": "Display name of the receiver",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "sharedBy",
"in": "query",
"description": "Display name of the sender",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "shareWith",
"in": "query",
"description": "ID of the user that receives the share",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "remoteId",
"in": "query",
"description": "ID of the remote",
"schema": {
"type": "integer",
"format": "int64",
"nullable": true
}
},
{
"name": "sharedByFederatedId",
"in": "query",
"description": "Federated ID of the sender",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "ownerFederatedId",
"in": "query",
"description": "Federated ID of the receiver",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares/{id}/reshare": {
"post": {
"operationId": "request_handler-re-share",
"summary": "create re-share on behalf of another user",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "shareWith",
"in": "query",
"description": "ID of the user that receives the share",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "remoteId",
"in": "query",
"description": "ID of the remote",
"schema": {
"type": "integer",
"format": "int64",
"nullable": true,
"default": 0
}
},
{
"name": "id",
"in": "path",
"description": "ID of the share",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Remote share returned",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"token",
"remoteId"
],
"properties": {
"token": {
"type": "string"
},
"remoteId": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Re-sharing is not possible",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares/{id}/permissions": {
"post": {
"operationId": "request_handler-update-permissions",
"summary": "update share information to keep federated re-shares in sync",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "permissions",
"in": "query",
"description": "New permissions",
"schema": {
"type": "integer",
"format": "int64",
"nullable": true
}
},
{
"name": "id",
"in": "path",
"description": "ID of the share",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Permissions updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
},
"400": {
"description": "Updating permissions is not possible",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares/{id}/accept": {
"post": {
"operationId": "request_handler-accept-share",
"summary": "accept server-to-server share",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "id",
"in": "path",
"description": "ID of the remote share",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Share accepted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
},
"500": {
"description": "",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares/{id}/decline": {
"post": {
"operationId": "request_handler-decline-share",
"summary": "decline server-to-server share",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "id",
"in": "path",
"description": "ID of the remote share",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares/{id}/unshare": {
"post": {
"operationId": "request_handler-unshare",
"summary": "remove server-to-server share if it was unshared by the owner",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "id",
"in": "path",
"description": "ID of the share",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares/{id}/revoke": {
"post": {
"operationId": "request_handler-revoke",
"summary": "federated share was revoked, either by the owner or the re-sharer",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "id",
"in": "path",
"description": "ID of the share",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Share revoked successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {}
}
}
}
}
}
}
},
"400": {
"description": "Revoking the share is not possible",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
},
"/ocs/v2.php/cloud/shares/{id}/move": {
"post": {
"operationId": "request_handler-move",
"summary": "change the owner of a server-to-server share",
"tags": [
"request_handler"
],
"security": [
{},
{
"bearer_auth": []
},
{
"basic_auth": []
}
],
"parameters": [
{
"name": "token",
"in": "query",
"description": "Shared secret between servers",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "remote",
"in": "query",
"description": "Address of the remote",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "remote_id",
"in": "query",
"description": "ID of the remote",
"schema": {
"type": "string",
"nullable": true
}
},
{
"name": "id",
"in": "path",
"description": "ID of the share",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
},
{
"name": "OCS-APIRequest",
"in": "header",
"required": true,
"schema": {
"type": "string",
"default": "true"
}
}
],
"responses": {
"200": {
"description": "Share moved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"ocs"
],
"properties": {
"ocs": {
"type": "object",
"required": [
"meta",
"data"
],
"properties": {
"meta": {
"$ref": "#/components/schemas/OCSMeta"
},
"data": {
"type": "object",
"required": [
"remote",
"owner"
],
"properties": {
"remote": {
"type": "string"
},
"owner": {
"type": "string"
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Moving share is not possible",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
}
}
}
}
}
},
"tags": [
{
"name": "mount_public_link",
"description": "Class MountPublicLinkController\nconvert public links to federated shares"
}
]
}

2
lib/public/Federation/ICloudFederationProvider.php
Unescape Escape View File

@ -66,7 +66,7 @@ interface ICloudFederationProvider {
* @param string $notificationType (e.g SHARE_ACCEPTED)
* @param string $providerId share ID
* @param array $notification provider specific notification
* @return array $data send back to sender
* @return array<string> $data send back to sender
*
* @throws ShareNotFound
* @throws ActionNotSupportedException

Write Preview
Loading…
Cancel
Save