Skip to main content

Spaces

Spaces API​

The Spaces API is implementing a subset of the functionality of the MS Graph Drives resource.

Example Space​

The JSON representation of a Drive, as handled by the Spaces API, looks like this:

{
  "driveAlias": "project/mars",
  "driveType": "project",
  "id": "storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925",
  "lastModifiedDateTime": "2023-01-24T21:19:26.417055+01:00",
  "name": "Mars",
  "owner": {
    "user": {
      "displayName": "",
      "id": "89ad5ad2-5fdb-4877-b8c9-601a9670b925"
    }
  },
  "quota": {
    "remaining": 999853685,
    "state": "normal",
    "total": 1000000000,
    "used": 146315
  },
  "root": {
    "eTag": "\"910af0061161c42d8d1224df6c4a2527\"",
    "id": "storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925",
    "permissions": [
      {
        "grantedToIdentities": [
          {
            "user": {
              "displayName": "Admin",
              "id": "some-admin-user-id-0000-000000000000"
            }
          }
        ],
        "roles": ["manager"]
      }
    ],
    "webDavUrl": "https://localhost:9200/dav/spaces/storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925"
  },
  "special": [
    {
      "eTag": "\"f97829324f63ce778095334cfeb0097b\"",
      "file": {
        "mimeType": "image/jpeg"
      },
      "id": "storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925!40171bea-3263-47a8-80ef-0ca20c37f45a",
      "lastModifiedDateTime": "2022-02-15T17:11:50.000000496+01:00",
      "name": "Mars_iStock-MR1805_20161221.jpeg",
      "size": 146250,
      "specialFolder": {
        "name": "image"
      },
      "webDavUrl": "https://localhost:9200/dav/spaces/storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925%2189ad5ad2-5fdb-4877-b8c9-601a9670b925/.space/Mars_iStock-MR1805_20161221.jpeg"
    },
    {
      "eTag": "\"ff38b31d8f109a4fbb98ab34499a3379\"",
      "file": {
        "mimeType": "text/markdown"
      },
      "id": "storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925!e2167612-7578-46e2-8ed7-971481037bc1",
      "lastModifiedDateTime": "2023-01-24T21:10:23.661841+01:00",
      "name": "readme.md",
      "size": 65,
      "specialFolder": {
        "name": "readme"
      },
      "webDavUrl": "https://localhost:9200/dav/spaces/storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925%2189ad5ad2-5fdb-4877-b8c9-601a9670b925/.space/readme.md"
    }
  ],
  "webUrl": "https://localhost:9200/f/storage-users-1$89ad5ad2-5fdb-4877-b8c9-601a9670b925"
}

Creating Spaces​

Create a single space POST /drives​

Create Drive

Create a space item (Enable sync) POST /drives/\{drive-id\}/root/children​

Create Drive Item

Reading Spaces​

GET https://cloud.opencloud.test/graph/{version}/{me/}drives/?{query-parameters}
ComponentDescription
{version}The version of the LibreGraph API used by the client.
{/me}The me component of the part is optional. If used, you only see spaces where the acting user is a regular member of.
{query-parameters}Optional parameters for the request to customize the response.

List all spaces GET /drives​

Returns a list of all available spaces, even ones where the acting user is not a regular member of. You need elevated permissions to do list all spaces. If you don't have the elevated permissions, the result is the same like GET /me/drives.

Multiple Administration Personas

The openCloud spaces concept draws a strict line between users which can work with the content of a space and others who have the permission to manage the space. A user which is able to manage quota and space metadata does not necessarily need to be able to access the content of a space.

Space Admin
There is a global user role "Space Admin" which grants users some global permissions to manage space quota and some space metadata. This Role enables the user also to disable, restore and delete spaces. He cannot manage space members.

Space Manager
The "Space Manager" is a user which is a regular member of a space because he has been invited. In addition to being part of a space the user can also manage the memberships of the space.

List My Spaces GET /me/drives​

List My Drives

Modifying Spaces​

Modify the properties of a space. You need elevated permissions to execute this request.

Set the space quota to 5GB PATCH /drives/\{drive-id\}​

To limit the quota of a space you need to set the quota.total value. The API response will give back all actual quota properties.

{
  "quota": {
    "remaining": 5368709120,
    "state": "normal",
    "total": 5368709120,
    "used": 0
  }
}
AttributeDescription
remainingThe remaining disk space in bytes. If the quota is not limited, this will show the total available disk space.
stateThe state of the space in regards to quota usage. This can be used for visual indicators. It can be normal(<75%), nearing(between 75% and 89%), critical(between 90% and 99%) and exceeded(100%).
totalThe space id. The value needs to be a space ID.
usedThe used disk space in bytes.
curl -L -k -X PATCH 'https://localhost:9200/graph/v1.0/drives/storage-users-1$535aa42d-a3c7-4329-9eba-5ef48fcaa3ff' \
-H 'Content-Type: application/json' \
--data-raw '{
    "quota": {
        "total": 5368709120
    }
}'

Change the space name, subtitle and alias PATCH /drives/\{drive-id\}​

You can change multiple space properties in one request as long as you submit a valid JSON body. Please be aware that some properties need different permissions.

curl -L -k -X PATCH 'https://localhost:9200/graph/v1.0/drives/storage-users-1$535aa42d-a3c7-4329-9eba-5ef48fcaa3ff' \
-H 'Content-Type: application/json' \
--data-raw '{
    "name": "Mars",
    "description": "Mission to mars",
    "driveAlias": "project/mission-to-mars"
}'

Disabling / Deleting Spaces​

Disable a space DELETE /drives/\{drive-id\}​

This operation will make the space content unavailable for all space members. No data will be deleted.

curl -L -k -X DELETE 'https://localhost:9200/graph/v1.0/drives/storage-users-1$535aa42d-a3c7-4329-9eba-5ef48fcaa3ff/'

Restore a space PATCH /drives/\{drive-id\}​

This operation will make the space content available again to all members. No content will be changed.

To restore a space, the Header Restore: T needs to be set.

curl -L -X PATCH 'https://localhost:9200/graph/v1.0/drives/storage-users-1$535aa42d-a3c7-4329-9eba-5ef48fcaa3ff/' \
-H 'Restore: T' \
-H 'Content-Type: text/plain' \
--data-raw '{}'
Body value

This request needs an empty body (--data-raw '') to fulfil the standard libregraph specification even when the body is not needed.

Permanently delete a space DELETE /drives/\{drive-id\}​

This operation will delete a space and all its data permanently. This is restricted to spaces which are already disabled.

To delete a space, the Header Purge: T needs to be set.

Request
curl -L -X DELETE 'https://localhost:9200/graph/v1.0/drives/storage-users-1$535aa42d-a3c7-4329-9eba-5ef48fcaa3ff' \
-H 'Purge: T'
Data will be deleted

This request will delete a space and all its content permanently. This operation cannot be reverted.

Sharing Space​

Add member to space POST /drives/\{drive-id\}/root/invite​

Invite

Sharing space as a link POST /drives/\{drive-id\}/root/createLink​

CreateLinkSpaceRoot

Reading Space Permissions​

Listing permissions of a space GET /drives/\{drive-id\}/root/permissions​

ListPermissionsSpaceRoot

Modifying / Deleting Space Permissions​

Update permissions of a drive PATCH /drives/\{drive-id\}/root/permissions/\{perm-id\}​

UpdatePermissionSpaceRoot

Set password of a link share POST /drives/\{drive-id\}/root/permissions/\{perm-id\}/setPassword​

SetPermissionPasswordSpaceRoot

Removing acess to a space DELETE /drives/\{drive-id\}/root/permissions/\{perm-id\}​

DeletePermissionSpaceRoot