diff --git a/.gitignore b/.gitignore index f814c22..71cdd40 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,11 @@ composer.lock vendor -tmp \ No newline at end of file +tmp + +# Generated by `make spec` (`scripts/compile-spec.sh`). +api/openapi-spec/v1.0.yaml + +# Local build artefacts. +build/ +spec/build/ +spec/node_modules/ diff --git a/.woodpecker/build-cpp-qt.yaml b/.woodpecker/build-cpp-qt.yaml index 7e26353..1994d2c 100644 --- a/.woodpecker/build-cpp-qt.yaml +++ b/.woodpecker/build-cpp-qt.yaml @@ -1,6 +1,7 @@ --- variables: - &alpine_image 'owncloudci/alpine:latest' + - &node_image 'node:22-alpine' - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5' - &environment HTTP_PROXY: @@ -21,20 +22,17 @@ steps: ref: HEAD path: libre-graph-api-cpp-qt-client remote: https://github.com/opencloud-eu/libre-graph-api-cpp-qt-client.git + compile-spec: + image: *node_image + environment: *environment + commands: + - sh scripts/compile-spec.sh generate-cpp-qt: image: *generator_image environment: *environment commands: - rm -Rf libre-graph-api-cpp-qt-client/* - - '/usr/local/bin/docker-entrypoint.sh generate - --enable-post-process-file - -i api/openapi-spec/v1.0.yaml - --additional-properties=packageName=libregraph - --git-user-id=opencloud-eu - --git-repo-id=libre-graph-api-cpp-qt-client - -g cpp-qt-client - -t templates/cpp-qt-client - -o libre-graph-api-cpp-qt-client' + - sh scripts/generate-cpp-qt-client.sh - cp LICENSE libre-graph-api-cpp-qt-client/LICENSE diff: image: *alpine_image @@ -62,9 +60,9 @@ steps: - commit - push followtags: true - message: ${CI_COMMIT_MESSAGE} - author_name: ${CI_COMMIT_AUTHOR} - author_email: ${CI_COMMIT_AUTHOR_EMAIL} + message: "${CI_COMMIT_MESSAGE}" + author_name: "${CI_COMMIT_AUTHOR}" + author_email: "${CI_COMMIT_AUTHOR_EMAIL}" netrc_password: from_secret: github_token netrc_username: diff --git a/.woodpecker/build-go.yaml b/.woodpecker/build-go.yaml index 2ce26b8..673650b 100644 --- a/.woodpecker/build-go.yaml +++ b/.woodpecker/build-go.yaml @@ -1,6 +1,7 @@ --- variables: - &alpine_image 'owncloudci/alpine:latest' + - &node_image 'node:22-alpine' - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5' - &environment HTTP_PROXY: @@ -21,20 +22,17 @@ steps: ref: HEAD path: libre-graph-api-go remote: https://github.com/opencloud-eu/libre-graph-api-go.git + compile-spec: + image: *node_image + environment: *environment + commands: + - sh scripts/compile-spec.sh generate-go: image: *generator_image environment: *environment commands: - rm -Rf libre-graph-api-go/* - - '/usr/local/bin/docker-entrypoint.sh generate - --enable-post-process-file - -i api/openapi-spec/v1.0.yaml - --additional-properties=packageName=libregraph - --git-user-id=opencloud-eu - --git-repo-id=libre-graph-api-go - -g go - -o libre-graph-api-go - --api-name-suffix Api' + - sh scripts/generate-go.sh - cp LICENSE libre-graph-api-go/LICENSE diff: image: *alpine_image @@ -62,9 +60,9 @@ steps: - commit - push followtags: true - message: ${CI_COMMIT_MESSAGE} - author_name: ${CI_COMMIT_AUTHOR} - author_email: ${CI_COMMIT_AUTHOR_EMAIL} + message: "${CI_COMMIT_MESSAGE}" + author_name: "${CI_COMMIT_AUTHOR}" + author_email: "${CI_COMMIT_AUTHOR_EMAIL}" netrc_password: from_secret: github_token netrc_username: diff --git a/.woodpecker/build-php.yaml b/.woodpecker/build-php.yaml index d7584f6..07d9e38 100644 --- a/.woodpecker/build-php.yaml +++ b/.woodpecker/build-php.yaml @@ -1,6 +1,7 @@ --- variables: - &alpine_image 'owncloudci/alpine:latest' + - &node_image 'node:22-alpine' - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5' - &environment HTTP_PROXY: @@ -21,20 +22,17 @@ steps: ref: HEAD path: libre-graph-api-php remote: https://github.com/opencloud-eu/libre-graph-api-php.git + compile-spec: + image: *node_image + environment: *environment + commands: + - sh scripts/compile-spec.sh generate-php: image: *generator_image environment: *environment commands: - rm -Rf libre-graph-api-php/* - - '/usr/local/bin/docker-entrypoint.sh generate - --enable-post-process-file - -i api/openapi-spec/v1.0.yaml - --additional-properties=packageName=libregraph - --git-user-id=opencloud-eu - --git-repo-id=libre-graph-api-php - -g php-nextgen - -t templates/php-nextgen - -o libre-graph-api-php' + - sh scripts/generate-php.sh - cp LICENSE libre-graph-api-php/LICENSE diff: image: *alpine_image @@ -62,9 +60,9 @@ steps: - commit - push followtags: true - message: ${CI_COMMIT_MESSAGE} - author_name: ${CI_COMMIT_AUTHOR} - author_email: ${CI_COMMIT_AUTHOR_EMAIL} + message: "${CI_COMMIT_MESSAGE}" + author_name: "${CI_COMMIT_AUTHOR}" + author_email: "${CI_COMMIT_AUTHOR_EMAIL}" netrc_password: from_secret: github_token netrc_username: diff --git a/.woodpecker/build-typescript-axios.yaml b/.woodpecker/build-typescript-axios.yaml index b3a0cd8..295ff11 100644 --- a/.woodpecker/build-typescript-axios.yaml +++ b/.woodpecker/build-typescript-axios.yaml @@ -1,6 +1,7 @@ --- variables: - &alpine_image 'owncloudci/alpine:latest' + - &node_image 'node:22-alpine' - &generator_image 'openapitools/openapi-generator-cli:v7.13.0@sha256:52b4b2bb6129b086b0f12614e98c884d378a84349fa114b07e20515702a793c5' - &environment HTTP_PROXY: @@ -21,20 +22,17 @@ steps: ref: HEAD path: libre-graph-api-typescript-axios remote: https://github.com/opencloud-eu/libre-graph-api-typescript-axios.git + compile-spec: + image: *node_image + environment: *environment + commands: + - sh scripts/compile-spec.sh generate-typescript-axios: image: *generator_image environment: *environment commands: - rm -Rf libre-graph-api-typescript-axios/* - - '/usr/local/bin/docker-entrypoint.sh generate - --enable-post-process-file - -i api/openapi-spec/v1.0.yaml - --additional-properties=packageName=libregraph - --git-user-id=opencloud-eu - --git-repo-id=libre-graph-api-typescript-axios - -g typescript-axios - -o libre-graph-api-typescript-axios - --api-name-suffix Api' + - sh scripts/generate-typescript-axios.sh - cp LICENSE libre-graph-api-typescript-axios/LICENSE diff: image: *alpine_image @@ -62,9 +60,9 @@ steps: - commit - push followtags: true - message: ${CI_COMMIT_MESSAGE} - author_name: ${CI_COMMIT_AUTHOR} - author_email: ${CI_COMMIT_AUTHOR_EMAIL} + message: "${CI_COMMIT_MESSAGE}" + author_name: "${CI_COMMIT_AUTHOR}" + author_email: "${CI_COMMIT_AUTHOR_EMAIL}" netrc_password: from_secret: github_token netrc_username: diff --git a/.woodpecker/docs.yaml b/.woodpecker/docs.yaml index a502744..b572810 100644 --- a/.woodpecker/docs.yaml +++ b/.woodpecker/docs.yaml @@ -1,10 +1,17 @@ --- +variables: + - &node_image 'node:22-alpine' + when: - event: push branch: ${CI_REPO_DEFAULT_BRANCH} - event: [ manual, tag] steps: + - name: compile-spec + image: *node_image + commands: + - sh scripts/compile-spec.sh - name: deploy-staging image: debian:latest environment: @@ -22,7 +29,7 @@ steps: - ssh-keyscan -t rsa $REMOTE_HOST >> $HOME/.ssh/known_hosts - echo "$SSH_KEY" > "$HOME/.ssh/id_rsa" - chmod 0600 $HOME/.ssh/id_rsa - - rsync -a --exclude '.git' --delete . $REMOTE_HOST:/var/swagger/libre-graph-api + - rsync -a --exclude '.git' --exclude 'spec/node_modules' --exclude 'spec/build' --exclude 'build' --delete . $REMOTE_HOST:/var/swagger/libre-graph-api - name: deploy-production image: debian:latest environment: @@ -39,4 +46,4 @@ steps: - ssh-keyscan -t rsa $REMOTE_HOST >> $HOME/.ssh/known_hosts - echo "$SSH_KEY" > "$HOME/.ssh/id_rsa" - chmod 0600 $HOME/.ssh/id_rsa - - rsync -a --exclude '.git' --delete . woodpeckersyncer@$REMOTE_HOST:/var/swagger/libre-graph-api + - rsync -a --exclude '.git' --exclude 'spec/node_modules' --exclude 'spec/build' --exclude 'build' --delete . woodpeckersyncer@$REMOTE_HOST:/var/swagger/libre-graph-api diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..9fab8f4 --- /dev/null +++ b/Makefile @@ -0,0 +1,51 @@ +# libre-graph-api local build entry points. +# +# `make` (or `make spec`) compiles the TypeSpec sources under spec/ into +# api/openapi-spec/v1.0.yaml. Per-language client generation targets pull the +# matching openapi-generator-cli image straight out of the woodpecker pipeline +# file for that language, so renovatebot remains the single source of truth +# for the generator version. + +SPEC := api/openapi-spec/v1.0.yaml +SPEC_SOURCES := $(wildcard spec/*.tsp) spec/tspconfig.yaml spec/package.json spec/package-lock.json +NODE_IMAGE := node:22-alpine + +# Extract `openapitools/openapi-generator-cli:@sha256:` from the +# .woodpecker pipeline file for the given language. +# $(call generator_image,go) +# $(call generator_image,typescript-axios) +generator_image = $(shell grep -oE "openapitools/openapi-generator-cli:[A-Za-z0-9._@:-]+" .woodpecker/build-$(1).yaml | head -n1) + +DOCKER_RUN = docker run --rm \ + --user $(shell id -u):$(shell id -g) \ + -v "$(CURDIR):/work" \ + -w /work + +.PHONY: all spec go typescript-axios php cpp-qt-client clean help + +all: spec + +help: ## Show this help + @echo "Common commands:" + @echo "" + @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}' + +spec: $(SPEC) ## Compile TypeSpec sources into api/openapi-spec/v1.0.yaml + +$(SPEC): $(SPEC_SOURCES) + $(DOCKER_RUN) -e HOME=/tmp -e npm_config_cache=/tmp/.npm $(NODE_IMAGE) sh scripts/compile-spec.sh + +go: $(SPEC) ## Generate the Go client into build/clients/go + $(DOCKER_RUN) -e OUTPUT_DIR=build/clients/go $(call generator_image,go) sh scripts/generate-go.sh + +typescript-axios: $(SPEC) ## Generate the TypeScript-Axios client into build/clients/typescript-axios + $(DOCKER_RUN) -e OUTPUT_DIR=build/clients/typescript-axios $(call generator_image,typescript-axios) sh scripts/generate-typescript-axios.sh + +php: $(SPEC) ## Generate the PHP client into build/clients/php + $(DOCKER_RUN) -e OUTPUT_DIR=build/clients/php $(call generator_image,php) sh scripts/generate-php.sh + +cpp-qt-client: $(SPEC) ## Generate the C++/Qt client into build/clients/cpp-qt-client + $(DOCKER_RUN) -e OUTPUT_DIR=build/clients/cpp-qt-client $(call generator_image,cpp-qt) sh scripts/generate-cpp-qt-client.sh + +clean: ## Remove build artefacts and the generated spec + rm -rf build/ spec/build/ $(SPEC) diff --git a/api/openapi-spec/v1.0.yaml b/api/openapi-spec/v1.0.yaml deleted file mode 100644 index 534c09e..0000000 --- a/api/openapi-spec/v1.0.yaml +++ /dev/null @@ -1,6234 +0,0 @@ -openapi: 3.0.1 -info: - title: Libre Graph API - description: Libre Graph is a free API for cloud collaboration inspired by the MS Graph API. - version: v1.0.8 - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html -servers: - - url: https://localhost:9200/graph - description: OpenCloud Development Setup -paths: - '/v1.0/me': - patch: - tags: - - me.user - summary: Update the current user - operationId: UpdateOwnUser - requestBody: - description: New user values - content: - application/json: - schema: - $ref: '#/components/schemas/userUpdate' - examples: - change preferred language: - value: - preferredLanguage: "en" - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/user' - default: - $ref: '#/components/responses/error' - get: - tags: - - me.user - summary: Get current user - operationId: GetOwnUser - parameters: - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - memberOf - type: string - responses: - '200': - description: Retrieved entity - content: - application/json: - schema: - $ref: '#/components/schemas/user' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1.0/me/changePassword: - post: - tags: - - me.changepassword - summary: Change your own password - operationId: ChangeOwnPassword - requestBody: - description: Password change request - content: - application/json: - schema: - title: Password change - type: object - required: - - currentPassword - - newPassword - properties: - currentPassword: - type: string - newPassword: - type: string - required: true - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1.0/me/photo/$value: - get: - tags: - - me.photo - summary: Get the current user's profile photo - operationId: GetOwnUserPhoto - responses: - '200': - description: Retrieved profile photo - content: - image/jpeg: - schema: - type: string - format: binary - default: - $ref: '#/components/responses/error' - put: - tags: - - me.photo - summary: Update the current user's profile photo - operationId: UpdateOwnUserPhotoPut - requestBody: - description: New user photo - content: - image/jpeg: - schema: - type: string - format: binary - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - patch: - tags: - - me.photo - summary: Update the current user's profile photo - operationId: UpdateOwnUserPhotoPatch - requestBody: - description: New user photo - content: - image/jpeg: - schema: - type: string - format: binary - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - delete: - tags: - - me.photo - summary: Delete the current user's profile photo - operationId: DeleteOwnUserPhoto - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1beta1/extensions/org.libregraph/activities': - get: - tags: - - activities - summary: Get activities - operationId: GetActivities - parameters: - - in: query - name: kql - schema: - type: string - example: resourceid:a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668 depth:2 - responses: - '200': - description: Found activities - content: - application/json: - schema: - title: Collection of activities - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/activity' - examples: - item activities: - value: - - id: "34646ab6-be32-43c9-89e6-987e0c237e9b" - times: - recordedTime: "2023-09-14T12:27:15" - template: - message: "{user} shared {resource}" - variables: - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - resource: - id: "7f92b0a9-06ad-49dc-890f-0e0a6eb4dea6$e9f01ca3-577f-4d1d-acd4-1cc44149ac25!5fb9f87c-a317-467b-9882-eb9f171564ac" - name: "secret stuff" - default: - $ref: '#/components/responses/error' - '/v1beta1/me/drives': - # $ref is buggy in the openapi-generator v7.0.1 - # $ref: '#/paths/~1v1.0~1me~1drives' - get: - tags: - - me.drives - summary: Alias for '/v1.0/drives', the difference is that grantedtoV2 is used and roles contain unified roles instead of cs3 roles - operationId: ListMyDrivesBeta - parameters: - - $ref: '#/components/parameters/orderby' - - $ref: '#/components/parameters/drivesFilter' - - $ref: '#/components/parameters/drivesExpand' - - $ref: '#/components/parameters/drivesSelect' - responses: - '200': - description: Retrieved spaces - content: - application/json: - schema: - title: Collection of drives - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/drive' - maxItems: 100 - '@odata.nextLink': - type: string - links: - root: - operationId: HomeGetRoot - default: - $ref: '#/components/responses/error' - x-ms-pageable: - nextLinkName: '@odata.nextLink' - operationName: listMore - x-ms-docs-operation-type: operation - /v1.0/me/drives: - get: - tags: - - me.drives - summary: Get all drives where the current user is a regular member of - operationId: ListMyDrives - parameters: - - $ref: '#/components/parameters/orderby' - - $ref: '#/components/parameters/drivesFilter' - responses: - '200': - description: Retrieved spaces - content: - application/json: - schema: - title: Collection of drives - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/drive' - maxItems: 100 - '@odata.nextLink': - type: string - links: - root: - operationId: HomeGetRoot - default: - $ref: '#/components/responses/error' - x-ms-pageable: - nextLinkName: '@odata.nextLink' - operationName: listMore - x-ms-docs-operation-type: operation - '/v1beta1/drives': - # $ref is buggy in the openapi-generator v7.0.1 - # $ref: '#/paths/~1v1.0~1drives' - get: - tags: - - drives.GetDrives - summary: Alias for '/v1.0/drives', the difference is that grantedtoV2 is used and roles contain unified roles instead of cs3 roles - operationId: ListAllDrivesBeta - parameters: - - $ref: '#/components/parameters/orderby' - - $ref: '#/components/parameters/drivesFilter' - - $ref: '#/components/parameters/drivesExpand' - - $ref: '#/components/parameters/drivesSelect' - responses: - '200': - description: Retrieved spaces - content: - application/json: - schema: - title: Collection of drives - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/drive' - links: - root: - operationId: GetRoot - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/drives': - get: - tags: - - drives.GetDrives - summary: Get all available drives - operationId: ListAllDrives - parameters: - - $ref: '#/components/parameters/orderby' - - $ref: '#/components/parameters/drivesFilter' - responses: - '200': - description: Retrieved spaces - content: - application/json: - schema: - title: Collection of drives - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/drive' - links: - root: - operationId: GetRoot - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - post: - tags: - - drives - summary: Create a new drive of a specific type - operationId: CreateDrive - requestBody: - description: New space property values - content: - application/json: - schema: - $ref: '#/components/schemas/drive' - examples: - multiple values: - value: - name: Mars - quota: - total: 1000000000 - description: Team space mars project - minimal: - value: - name: Venus - required: true - responses: - '201': - description: Created - content: - application/json: - schema: - $ref: '#/components/schemas/drive' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/drives/{drive-id}': - get: - tags: - - drives - summary: Get drive by id - operationId: GetDrive - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - $ref: '#/components/parameters/drivesSelect' - responses: - '200': - description: Retrieved drive - content: - application/json: - schema: - $ref: '#/components/schemas/drive' - links: - root: - operationId: GetRoot - parameters: - drive-id: $request.path.drive-id - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - patch: - tags: - - drives - summary: Update the drive - operationId: UpdateDrive - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - requestBody: - description: New space values - content: - application/json: - schema: - $ref: '#/components/schemas/driveUpdate' - examples: - change quota: - value: - quota: - total: 1000000000 - change name: - value: - name: Physics - change description: - value: - description: Marketing team collaboration area - change drive image: - value: - special: - id: 408f26e3-d6d8-4aa4-bd5c-3fd6f5032b51$aba2bafc-e1a0-421e-a37a-9acf5f655f83!14fd3432-e8d9-42a7-9446-2e3fd621afca - specialFolder: - name: image - change drive readme: - value: - special: - id: 408f26e3-d6d8-4aa4-bd5c-3fd6f5032b51$aba2bafc-e1a0-421e-a37a-9acf5f655f83!14fd3432-e8d9-42a7-9446-2e3fd621afca - specialFolder: - name: readme - required: true - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/drive' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - delete: - tags: - - drives - summary: Delete a specific space - operationId: DeleteDrive - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: If-Match - in: header - description: ETag - schema: - type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/root/children': - post: - tags: - - drives.root - summary: Create a drive item - operationId: CreateDriveItem - description: | - You can use the root childrens endpoint to mount a remoteItem in the share jail. The `@client.synchronize` property of the `driveItem` in the [sharedWithMe](#/me.drive/ListSharedWithMe) endpoint will change to true. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668 - x-ms-docs-key-type: drive - requestBody: - description: In the request body, provide a JSON object with the following parameters. For mounting a share the necessary remoteItem id and permission id can be taken from the [sharedWithMe](#/me.drive/ListSharedWithMe) endpoint. - content: - application/json: - schema: - $ref: '#/components/schemas/driveItem' - examples: - mount a shared remoteId: - value: - name: Einsteins project share - remoteItem: - id: a-storage-provider-id$a-space-id!a-node-id - responses: - '200': - description: Response - content: - application/json: - schema: - $ref: '#/components/schemas/driveItem' - example: - name: Einsteins project share - id: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!share-id - remoteItem: - id: a-storage-provider-id$a-space-id!a-node-id - name: Project - parentReference: - driveID: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668 - id: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!a0ca6a90-a365-4782-871e-d44447bbc668 - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/root/createLink': - post: - tags: - - drives.root - summary: Create a sharing link for the root item of a Drive - operationId: CreateLinkSpaceRoot - description: | - You can use the createLink action to share a driveItem via a sharing link. - - The response will be a permission object with the link facet containing the created link details. - - ## Link types - - For now, The following values are allowed for the type parameter. - - | Value | Display name | Description | - | -------------- | ----------------- | --------------------------------------------------------------- | - | view | View | Creates a read-only link to the driveItem. | - | upload | Upload | Creates a read-write link to the folder driveItem. | - | edit | Edit | Creates a read-write link to the driveItem. | - | createOnly | File Drop | Creates an upload-only link to the folder driveItem. | - | blocksDownload | Secure View | Creates a read-only link that blocks download to the driveItem. | - - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - requestBody: - description: In the request body, provide a JSON object with the following parameters. - content: - application/json: - schema: - $ref: '#/components/schemas/driveItemCreateLink' - examples: - create viewer link: - value: - type: "view" - create editor link with custom display name: - value: - type: "edit" - displayName: "Homework" - create editor link with expiry: - value: - type: "edit" - expirationDateTime: "2018-07-15T14:00:00.000Z" - responses: - '200': - description: Response - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - create viewer link: - value: - - id: "7181275c-557e-4adf-8e44-abdcf5389b6a" - link: - type: "view" - webUrl: "https://cloud.example.org/s/YlaySZdHCRHUDeE" - create editor link with custom display name: - value: - - id: "7181275c-557e-4adf-8e44-abdcf5389b6a" - link: - type: "edit" - displayName: "Homework" - webUrl: "https://cloud.example.org/s/fdleMyGeerkIZTJ" - create editor link with expiry: - value: - - id: "a373c812-d786-42ae-a65f-ed87ee4abd49" - link: - type: "edit" - webUrl: "https://cloud.example.org/s/MlnTDkhcBlihNzO" - '207': - # FIXME describe partial success response - description: Partial success response TODO - default: - $ref: '#/components/responses/error' - # TODO add SendNotification errors as per https://learn.microsoft.com/en-us/graph/api/driveitem-invite?view=graph-rest-beta&tabs=http#sendnotification-errors - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/root/invite': - post: - tags: - - drives.root - summary: Send a sharing invitation - operationId: InviteSpaceRoot - description: | - Sends a sharing invitation for the root of a `drive`. A sharing invitation provides permissions to the - recipients and optionally sends them an email with a sharing link. - - The response will be a permission object with the grantedToV2 property containing the created grant details. - - ## Roles property values - For now, roles are only identified by a uuid. There are no hardcoded aliases like `read` or `write` because role actions can be completely customized. - # FIXME we should add isBuiltIn and isEnabled to unifiedRoleDefinition so we can use speaking role ids in examples and establish a well defined set of roles. - # By throwing around only uuids we increase the risk of someone choosing an ambiguous or misleading displayname. We will have to define a set of default - # sharing permissions. For those we should use speaking ids. - # - # For now, the following roles are considered built in: - # - # | Role | Value | Description | - # | ------- | ------- | --------------------------------------------------------------------------------------------------------------------- | - # | Viewer | `read` | Provides the ability to read the metadata and contents of the item. | - # | Editor | `write` | Provides the ability to read and modify the metadata and contents of the item. | - # | Manager | `owner` | For project drives this represents the Manager role to mimic ms graph | - # - # More built in roles will be added with a speaking value but clients **MUST** treat the value as an - # opaque identifier as custom roles will be using UUIDs. - - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - requestBody: - description: In the request body, provide a JSON object with the following parameters. To create a custom role submit a list of actions instead of roles. - content: - application/json: - schema: - $ref: '#/components/schemas/driveItemInvite' - examples: - send viewer invite: - value: - recipients: - - '@libre.graph.recipient.type': user - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - send viewer invite to multiple recipients: - value: - recipients: - - '@libre.graph.recipient.type': user - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - - '@libre.graph.recipient.type': user - objectId: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - send editor invite with expiry: - value: - recipients: - - '@libre.graph.recipient.type': user - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ] - expirationDateTime: "2018-07-15T14:00:00.000Z" - send manager invite to group: - description: "Sharing with a groups requires setting the @libre.graph.recipient.type annotation." - value: - recipients: - - '@libre.graph.recipient.type': group - objectId: "167cbee2-0518-455a-bfb2-031fe0621e5d" - roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ] - send invite to user granting custom actions: - description: "A Custom role is just a collection of actions, in this case allowing the user to stat and move driveItems" - value: - recipients: - - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - '@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ] - responses: - '200': - description: Response - content: - application/json: - schema: - title: Collection of permissions - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/permission' - examples: - send viewer invite: - value: - - id: "34646ab6-be32-43c9-89e6-987e0c237e9b" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - send viewer invite to multiple recipients: - description: multiple permissions are returned as each has received a dedicated sharing id - value: - - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - - id: "b470677e-a7f5-4304-8ef5-f5056a21fff1" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c" - displayName: "Marie Skłodowska Curie" - send editor invite with expiry: - value: - - id: "453b02be-4ec2-4e7d-b576-09fc153de812" - roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - expirationDateTime: "2018-07-15T14:00:00.000Z" - send manager invite to group: - value: - - id: "86765c0d-3905-444a-9b07-76201f8cf7df" - roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ] - grantedToV2: - - group: - id: "167cbee2-0518-455a-bfb2-031fe0621e5d" - displayName: "Philosophy Haters" - send invite to user granting custom actions: - value: - - id: "c42b5cbd-2d65-42cf-b0b6-fb6d2b762256" - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - '@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ] - '207': - # FIXME describe partial success response - description: Partial success response TODO - '400': - description: Bad request - content: - application/json: - schema: - $ref: '#/components/schemas/odata.error' - examples: - secureSharingInvalidRequest: - description: If the recipient was given via email, but does not belong to a known user account. - value: - - error: - - code: invalidRequest - message: Some users in the request cannot be invited securely. - innerError: - - code: secureSharingInvalidRequest - date: "2023-09-14T12:27:15" - request-id: b49f582d-9a0f-4731-ab0c-b9e50246ef58 - client-request-id: 832c7206-1a40-395c-e0d9-e85649b8b0b0 - default: - $ref: '#/components/responses/error' - # TODO add SendNotification errors as per https://learn.microsoft.com/en-us/graph/api/driveitem-invite?view=graph-rest-beta&tabs=http#sendnotification-errors - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/root/permissions': - get: - tags: - - drives.root - summary: List the effective permissions on the root item of a drive. - operationId: ListPermissionsSpaceRoot - description: | - The permissions collection includes potentially sensitive information and may not be available for every caller. - - * For the owner of the item, all sharing permissions will be returned. This includes co-owners. - * For a non-owner caller, only the sharing permissions that apply to the caller are returned. - * Sharing permission properties that contain secrets (e.g. `webUrl`) are only returned for callers that are able to create the sharing permission. - - All permission objects have an `id`. A permission representing - * a link has the `link` facet filled with details. - * a share has the `roles` property set and the `grantedToV2` property filled with the grant recipient details. - - # TODO hm, the ms graph api seems to always fill the `roles` property to indicate the actions granted by the link. - # | Value | Display name | Description | role? | - # | -------------- | ----------------- | --------------------------------------------------------------- | -------------- | - # | view | View | Creates a read-only link to the driveItem. | viewer | - # | upload | Upload | Creates a read-write link to the folder driveItem. | uploader | - # | edit | Edit | Creates a read-write link to the driveItem. | editor | - # | createOnly | File Drop | Creates an upload-only link to the folder driveItem. | createOnly | - # | blocksDownload | Secure View | Creates a read-only link that blocks download to the driveItem. | blocksDownload | - # AFAICT we will have to define the actions granted by a link type when we start to implement this - # but e.g. a createOnly role and blocksDownload should not show up in the drop down for sharing files internally ... - # when we need to hardcode this anyway ... we should indicate that by using the buildIn flag ... but how do we prevent some roles from showing up in the internal sharing dialog ... - # for now leave out the roles property and hardcode the actions allowed by the link type - - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - $ref: '#/components/parameters/permissionsFilter' - - $ref: '#/components/parameters/permissionsSelect' - - $ref: '#/components/parameters/count' - - $ref: '#/components/parameters/top' - responses: - '200': - description: Retrieved resource - content: - application/json: - schema: - title: Collection of permissions with allowed values - type: object - properties: - '@libre.graph.permissions.roles.allowedValues': - type: array - description: A list of role definitions that can be chosen for the resource. - items: - $ref: '#/components/schemas/unifiedRoleDefinition' - '@libre.graph.permissions.actions.allowedValues': - type: array - description: | - A list of actions that can be chosen for a custom role. - - Following the CS3 API we can represent the CS3 permissions by mapping them to driveItem properties or relations like this: - | [CS3 ResourcePermission](https://cs3org.github.io/cs3apis/#cs3.storage.provider.v1beta1.ResourcePermissions) | action | comment | - | ------------------------------------------------------------------------------------------------------------ | ------ | ------- | - | `stat` | `libre.graph/driveItem/basic/read` | `basic` because it does not include versions or trashed items | - | `get_quota` | `libre.graph/driveItem/quota/read` | read only the `quota` property | - | `get_path` | `libre.graph/driveItem/path/read` | read only the `path` property | - | `move` | `libre.graph/driveItem/path/update` | allows updating the `path` property of a CS3 resource | - | `delete` | `libre.graph/driveItem/standard/delete` | `standard` because deleting is a common update operation | - | `list_container` | `libre.graph/driveItem/children/read` | | - | `create_container` | `libre.graph/driveItem/children/create` | | - | `initiate_file_download` | `libre.graph/driveItem/content/read` | `content` is the property read when initiating a download | - | `initiate_file_upload` | `libre.graph/driveItem/upload/create` | `uploads` are a separate property. postprocessing creates the `content` | - | `add_grant` | `libre.graph/driveItem/permissions/create` | | - | `list_grant` | `libre.graph/driveItem/permissions/read` | | - | `update_grant` | `libre.graph/driveItem/permissions/update` | | - | `remove_grant` | `libre.graph/driveItem/permissions/delete` | | - | `deny_grant` | `libre.graph/driveItem/permissions/deny` | uses a non CRUD action `deny` | - | `list_file_versions` | `libre.graph/driveItem/versions/read` | `versions` is a `driveItemVersion` collection | - | `restore_file_version` | `libre.graph/driveItem/versions/update` | the only `update` action is restore | - | `list_recycle` | `libre.graph/driveItem/deleted/read` | reading a driveItem `deleted` property implies listing | - | `restore_recycle_item` | `libre.graph/driveItem/deleted/update` | the only `update` action is restore | - | `purge_recycle` | `libre.graph/driveItem/deleted/delete` | allows purging deleted `driveItems` | - items: - type: string - value: - type: array - items: - $ref: '#/components/schemas/permission' - # maxItems: 100 - '@odata.count': - type: integer - description: The total number of permissions available, only present if the `count` query parameter is set to true. - #'@odata.nextLink': - # type: string - example: - '@libre.graph.permissions.roles.allowedValues': - - id: b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 - description: "Allows reading the shared file or folder" - displayName: Viewer - # we don't want to reproduce all the individual role permissions, that is what the /roleManagement/permissions/roleDefinitions endpoint is for - # to build a custom role - #rolePermissions: - # - allowedResourceActions: - # - libre.graph/driveItem/basic/read - # - libre.graph/driveItem/permissions/read - # - libre.graph/driveItem/upload/create - # condition: "exists @Resource.File" - '@libre.graph.weight': 1 - - id: fb6c3e19-e378-47e5-b277-9732f9de6e21 - description: "Allows reading and writing the shared file or folder" - displayName: Editor - #rolePermissions: - # - allowedResourceActions: - # - libre.graph/driveItem/standard/allTasks - # condition: "exists @Resource.File" - '@libre.graph.weight': 2 - - id: 312c0871-5ef7-4b3a-85b6-0e4074c64049 - description: "Allows managing a space" - displayName: Manager - #rolePermissions: - # - allowedResourceActions: - # - libre.graph/drive/standard/allTasks - # condition: "exists @Resource.File" - '@libre.graph.weight': 3 - - id: 4916f47e-66d5-49bb-9ac9-748ad00334b - description: "Allows creating new files" - displayName: File Drop - #rolePermissions: - # - allowedResourceActions: - # libre.graph/driveItem/upload/create - # condition: "exists @Resource.File" - '@libre.graph.weight': 4 - '@libre.graph.permissions.actions.allowedValues': [ - "libre.graph/driveItem/basic/read", - "libre.graph/driveItem/permissions/read", - "libre.graph/driveItem/upload/create", - "libre.graph/driveItem/standard/allTasks", - "libre.graph/driveItem/upload/create" - ] - - value: - - id: "67445fde-a647-4dd4-b015-fc5dafd2821d" - link: - type: "view" - webUrl: "https://cloud.example.org/s/fhGBMIkKFEHWysj" - - - id: "34646ab6-be32-43c9-89e6-987e0c237e9b" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - - id: "b470677e-a7f5-4304-8ef5-f5056a21fff1" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c" - displayName: "Marie Skłodowska Curie" - - id: "453b02be-4ec2-4e7d-b576-09fc153de812" - roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - expirationDateTime: "2018-07-15T14:00:00.000Z" - - id: "86765c0d-3905-444a-9b07-76201f8cf7df" - roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ] - grantedToV2: - - group: - id: "167cbee2-0518-455a-bfb2-031fe0621e5d" - displayName: "Philosophy Haters" - - id: "c42b5cbd-2d65-42cf-b0b6-fb6d2b762256" - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - '@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ] - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/root/permissions/{perm-id}': - get: - tags: - - drives.root - summary: Get a single sharing permission for the root item of a drive - operationId: GetPermissionSpaceRoot - description: | - Return the effective sharing permission for a particular permission resource. - - # TODO do we need to implement inherited permissions from the start? - # Effective permissions of an item can come from two sources: permissions set directly on the item itself or permissions that are inherited from the item's ancestors. - # - # Callers can differentiate if the permission is inherited or not by checking the `inheritedFrom` property. This property is an ItemReference resource referencing the ancestor that the permission is inherited from. - # - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - responses: - '200': - description: Retrieved resource - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - edit permission: - value: - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "write" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - patch: - tags: - - drives.root - summary: Update sharing permission - operationId: UpdatePermissionSpaceRoot - description: | - Update the properties of a sharing permission by patching the permission resource. - - Only the `roles`, `expirationDateTime` and `password` properties can be modified this way. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - #- name: If-Match - # in: header - # description: | - # If this request header is included and the eTag (or cTag) provided does not match the current tag on the item, - # a `412 Precondition Failed`` response is returned and the item will not be updated. - # schema: - # type: string - requestBody: - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - update link: - description: Updating a public link is done by setting the `type` property of the permission link. - value: - link: - type: edit - update invite: - description: Updating an invite is done by setting the `roles` property of the permission. - value: - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - required: true - responses: - '200': - description: Updated permission - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - update link: - value: - id: "a373c812-d786-42ae-a65f-ed87ee4abd49" - link: - type: "edit" - webUrl: "https://cloud.example.org/s/MlnTDkhcBlihNzO" - update invite: - value: - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - expirationDateTime: "2018-07-15T14:00:00.000Z" - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - delete: - tags: - - drives.root - summary: Remove access to a Drive - operationId: DeletePermissionSpaceRoot - description: | - Remove access to the root item of a drive. - - Only sharing permissions that are not inherited can be deleted. The `inheritedFrom` property must be `null`. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - #- name: If-Match - # in: header - # description: | - # If this request header is included and the eTag (or cTag) provided does not match the current tag on the item, - # a `412 Precondition Failed`` response is returned and the item will not be updated. - # schema: - # type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/root/permissions/{perm-id}/setPassword': - post: - tags: - - drives.root - summary: Set sharing link password for the root item of a drive - operationId: SetPermissionPasswordSpaceRoot - description: | - Set the password of a sharing permission. - - Only the `password` property can be modified this way. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - #- name: If-Match - # in: header - # description: | - # If this request header is included and the eTag (or cTag) provided does not match the current tag on the item, - # a `412 Precondition Failed`` response is returned and the item will not be updated. - # schema: - # type: string - requestBody: - description: New password value - content: - application/json: - schema: - $ref: '#/components/schemas/sharingLinkPassword' - examples: - set password: - value: - password: "TestPassword123!" - set empty password: - value: - password: "" - required: true - responses: - '200': - description: Updated permission - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - set password on editor link with custom display name: - value: - - id: "7181275c-557e-4adf-8e44-abdcf5389b6a" - hasPassword: true - expirationDateTime: "2018-07-15T14:00:00.000Z" - link: - type: "edit" - displayName: "Homework" - webUrl: "https://cloud.example.org/s/fdleMyGeerkIZTJ" - set empty password: - value: - - id: "765c9b7b-6ccf-46ff-a659-95501250229c" - hasPassword: false - link: - type: "view" - displayName: "Quick link" - quicklink: true - webUrl: "https://cloud.example.org/s/erjHgjKjkstTesG" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/items/{item-id}': - get: - tags: - - driveItem - summary: Get a DriveItem. - operationId: GetDriveItem - description: | - Get a DriveItem by using its ID. - parameters: - - name: drive-id - in: path - description: "key: id of drive" - required: true - schema: - type: string - example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668 - x-ms-docs-key-type: drive - - name: item-id - in: path - description: "key: id of item" - required: true - schema: - type: string - example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!share-id - x-ms-docs-key-type: item - - $ref: '#/components/parameters/driveItemSelect' - responses: - "200": - description: Retrieved driveItem - content: - application/json: - schema: - $ref: "#/components/schemas/driveItem" - default: - $ref: "#/components/responses/error" - x-ms-docs-operation-type: operation - patch: - tags: - - driveItem - summary: Update a DriveItem. - operationId: UpdateDriveItem - description: | - Update a DriveItem. - - The request body must include a JSON object with the properties to update. - Only the properties that are provided will be updated. - - Currently it supports updating the following properties: - - * `@UI.Hidden` - Hides the item from the UI. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668 - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!share-id - x-ms-docs-key-type: item - requestBody: - description: DriveItem properties to update - content: - application/json: - schema: - $ref: '#/components/schemas/driveItem' - examples: - change visibility: - value: - "@UI.Hidden": true - required: true - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/driveItem' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - delete: - tags: - - driveItem - summary: Delete a DriveItem. - operationId: DeleteDriveItem - description: | - Delete a DriveItem by using its ID. - - Deleting items using this method moves the items to the recycle bin instead of permanently deleting the item. - - Mounted shares in the share jail are unmounted. The `@client.synchronize` property of the `driveItem` in the [sharedWithMe](#/me.drive/ListSharedWithMe) endpoint will change to false. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668 - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!share-id - x-ms-docs-key-type: item - #- name: If-Match - # in: header - # description: | - # If this request header is included and the eTag (or cTag) provided does not match the current tag on the item, - # a `412 Precondition Failed`` response is returned and the item will not be updated. - # schema: - # type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/items/{item-id}/content': - get: - tags: - - driveItem - summary: Download the content of a DriveItem - operationId: GetDriveItemContent - description: | - Download the contents of the primary stream (file) of a driveItem. Only - driveItem objects with a `file` facet can be downloaded. - - The response is a `302 Found` redirecting to a pre-authenticated download - URL for the file. This is the same URL that is returned via the - `@microsoft.graph.downloadUrl` instance annotation on the driveItem when - requested via `$select`. Choose between the two based on whether you - want to call the redirecting `/content` endpoint directly (for example, - with a client that follows redirects automatically) or you want to - inspect / schedule / prefetch the URL yourself via the annotation. - - The pre-authenticated URL is short-lived and does not require an - `Authorization` header. - - To download a partial range of bytes, apply the `Range` header to the - redirect target (the pre-authenticated URL), not to the `/content` - request. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - responses: - '302': - description: Pre-authenticated redirect to the file content. - headers: - Location: - required: true - schema: - type: string - format: uri - description: The pre-authenticated URL where the content can be downloaded. - '404': - description: The driveItem was not found or is not a file. - content: - application/json: - schema: - $ref: '#/components/schemas/odata.error' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/items/{item-id}/createLink': - post: - tags: - - drives.permissions - summary: Create a sharing link for a DriveItem - operationId: CreateLink - description: | - You can use the createLink action to share a driveItem via a sharing link. - - The response will be a permission object with the link facet containing the created link details. - - ## Link types - - For now, The following values are allowed for the type parameter. - - | Value | Display name | Description | - | -------------- | ----------------- | --------------------------------------------------------------- | - | view | View | Creates a read-only link to the driveItem. | - | upload | Upload | Creates a read-write link to the folder driveItem. | - | edit | Edit | Creates a read-write link to the driveItem. | - | createOnly | File Drop | Creates an upload-only link to the folder driveItem. | - | blocksDownload | Secure View | Creates a read-only link that blocks download to the driveItem. | - - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - requestBody: - description: In the request body, provide a JSON object with the following parameters. - content: - application/json: - schema: - $ref: '#/components/schemas/driveItemCreateLink' - examples: - create viewer link: - value: - type: "view" - create editor link with custom display name: - value: - type: "edit" - displayName: "Homework" - create editor link with expiry: - value: - type: "edit" - expirationDateTime: "2018-07-15T14:00:00.000Z" - responses: - '200': - description: Response - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - create viewer link: - value: - - id: "7181275c-557e-4adf-8e44-abdcf5389b6a" - link: - type: "view" - webUrl: "https://cloud.example.org/s/YlaySZdHCRHUDeE" - create editor link with custom display name: - value: - - id: "7181275c-557e-4adf-8e44-abdcf5389b6a" - link: - type: "edit" - displayName: "Homework" - webUrl: "https://cloud.example.org/s/fdleMyGeerkIZTJ" - create editor link with expiry: - value: - - id: "a373c812-d786-42ae-a65f-ed87ee4abd49" - link: - type: "edit" - webUrl: "https://cloud.example.org/s/MlnTDkhcBlihNzO" - '207': - # FIXME describe partial success response - description: Partial success response TODO - default: - $ref: '#/components/responses/error' - # TODO add SendNotification errors as per https://learn.microsoft.com/en-us/graph/api/driveitem-invite?view=graph-rest-beta&tabs=http#sendnotification-errors - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/items/{item-id}/invite': - post: - tags: - - drives.permissions - summary: Send a sharing invitation - operationId: Invite - description: | - Sends a sharing invitation for a `driveItem`. A sharing invitation provides permissions to the - recipients and optionally sends them an email with a sharing link. - - The response will be a permission object with the grantedToV2 property containing the created grant details. - - ## Roles property values - For now, roles are only identified by a uuid. There are no hardcoded aliases like `read` or `write` because role actions can be completely customized. - # FIXME we should add isBuiltIn and isEnabled to unifiedRoleDefinition so we can use speaking role ids in examples and establish a well defined set of roles. - # By throwing around only uuids we increase the risk of someone choosing an ambiguous or misleading displayname. We will have to define a set of default - # sharing permissions. For those we should use speaking ids. - # - # For now, the following roles are considered built in: - # - # | Role | Value | Description | - # | ------- | ------- | --------------------------------------------------------------------------------------------------------------------- | - # | Viewer | `read` | Provides the ability to read the metadata and contents of the item. | - # | Editor | `write` | Provides the ability to read and modify the metadata and contents of the item. | - # | Manager | `owner` | For project drives this represents the Manager role to mimic ms graph | - # - # More built in roles will be added with a speaking value but clients **MUST** treat the value as an - # opaque identifier as custom roles will be using UUIDs. - - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - requestBody: - description: In the request body, provide a JSON object with the following parameters. To create a custom role submit a list of actions instead of roles. - content: - application/json: - schema: - $ref: '#/components/schemas/driveItemInvite' - examples: - send viewer invite: - value: - recipients: - - '@libre.graph.recipient.type': user - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - send viewer invite to multiple recipients: - value: - recipients: - - '@libre.graph.recipient.type': user - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - - '@libre.graph.recipient.type': user - objectId: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - send editor invite with expiry: - value: - recipients: - - '@libre.graph.recipient.type': user - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ] - expirationDateTime: "2018-07-15T14:00:00.000Z" - send manager invite to group: - description: "Sharing with a groups requires setting the @libre.graph.recipient.type annotation." - value: - recipients: - - '@libre.graph.recipient.type': group - objectId: "167cbee2-0518-455a-bfb2-031fe0621e5d" - roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ] - send invite to user granting custom actions: - description: "A Custom role is just a collection of actions, in this case allowing the user to stat and move driveItems" - value: - recipients: - - objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51" - '@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ] - responses: - '200': - description: Response - content: - application/json: - schema: - title: Collection of permissions - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/permission' - examples: - send viewer invite: - value: - - id: "34646ab6-be32-43c9-89e6-987e0c237e9b" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - send viewer invite to multiple recipients: - description: multiple permissions are returned as each has received a dedicated sharing id - value: - - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - - id: "b470677e-a7f5-4304-8ef5-f5056a21fff1" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c" - displayName: "Marie Skłodowska Curie" - send editor invite with expiry: - value: - - id: "453b02be-4ec2-4e7d-b576-09fc153de812" - roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - expirationDateTime: "2018-07-15T14:00:00.000Z" - send manager invite to group: - value: - - id: "86765c0d-3905-444a-9b07-76201f8cf7df" - roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ] - grantedToV2: - - group: - id: "167cbee2-0518-455a-bfb2-031fe0621e5d" - displayName: "Philosophy Haters" - send invite to user granting custom actions: - value: - - id: "c42b5cbd-2d65-42cf-b0b6-fb6d2b762256" - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - '@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ] - '207': - # FIXME describe partial success response - description: Partial success response TODO - '400': - description: Bad request - content: - application/json: - schema: - $ref: '#/components/schemas/odata.error' - examples: - secureSharingInvalidRequest: - description: If the recipient was given via email, but does not belong to a known user account. - value: - - error: - - code: invalidRequest - message: Some users in the request cannot be invited securely. - innerError: - - code: secureSharingInvalidRequest - date: "2023-09-14T12:27:15" - request-id: b49f582d-9a0f-4731-ab0c-b9e50246ef58 - client-request-id: 832c7206-1a40-395c-e0d9-e85649b8b0b0 - default: - $ref: '#/components/responses/error' - # TODO add SendNotification errors as per https://learn.microsoft.com/en-us/graph/api/driveitem-invite?view=graph-rest-beta&tabs=http#sendnotification-errors - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/items/{item-id}/permissions': - get: - tags: - - drives.permissions - summary: List the effective sharing permissions on a driveItem. - operationId: ListPermissions - description: | - The permissions collection includes potentially sensitive information and may not be available for every caller. - - * For the owner of the item, all sharing permissions will be returned. This includes co-owners. - * For a non-owner caller, only the sharing permissions that apply to the caller are returned. - * Sharing permission properties that contain secrets (e.g. `webUrl`) are only returned for callers that are able to create the sharing permission. - - All permission objects have an `id`. A permission representing - * a link has the `link` facet filled with details. - * a share has the `roles` property set and the `grantedToV2` property filled with the grant recipient details. - - # TODO hm, the ms graph api seems to always fill the `roles` property to indicate the actions granted by the link. - # | Value | Display name | Description | role? | - # | -------------- | ----------------- | --------------------------------------------------------------- | -------------- | - # | view | View | Creates a read-only link to the driveItem. | viewer | - # | upload | Upload | Creates a read-write link to the folder driveItem. | uploader | - # | edit | Edit | Creates a read-write link to the driveItem. | editor | - # | createOnly | File Drop | Creates an upload-only link to the folder driveItem. | createOnly | - # | blocksDownload | Secure View | Creates a read-only link that blocks download to the driveItem. | blocksDownload | - # AFAICT we will have to define the actions granted by a link type when we start to implement this - # but e.g. a createOnly role and blocksDownload should not show up in the drop down for sharing files internally ... - # when we need to hardcode this anyway ... we should indicate that by using the buildIn flag ... but how do we prevent some roles from showing up in the internal sharing dialog ... - # for now leave out the roles property and hardcode the actions allowed by the link type - - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - - $ref: '#/components/parameters/permissionsFilter' - - $ref: '#/components/parameters/permissionsSelect' - - $ref: '#/components/parameters/count' - - $ref: '#/components/parameters/top' - responses: - '200': - description: Retrieved resource - content: - application/json: - schema: - title: Collection of permissions with allowed values - type: object - properties: - '@libre.graph.permissions.roles.allowedValues': - type: array - description: A list of role definitions that can be chosen for the resource. - items: - $ref: '#/components/schemas/unifiedRoleDefinition' - '@libre.graph.permissions.actions.allowedValues': - type: array - description: | - A list of actions that can be chosen for a custom role. - - Following the CS3 API we can represent the CS3 permissions by mapping them to driveItem properties or relations like this: - | [CS3 ResourcePermission](https://cs3org.github.io/cs3apis/#cs3.storage.provider.v1beta1.ResourcePermissions) | action | comment | - | ------------------------------------------------------------------------------------------------------------ | ------ | ------- | - | `stat` | `libre.graph/driveItem/basic/read` | `basic` because it does not include versions or trashed items | - | `get_quota` | `libre.graph/driveItem/quota/read` | read only the `quota` property | - | `get_path` | `libre.graph/driveItem/path/read` | read only the `path` property | - | `move` | `libre.graph/driveItem/path/update` | allows updating the `path` property of a CS3 resource | - | `delete` | `libre.graph/driveItem/standard/delete` | `standard` because deleting is a common update operation | - | `list_container` | `libre.graph/driveItem/children/read` | | - | `create_container` | `libre.graph/driveItem/children/create` | | - | `initiate_file_download` | `libre.graph/driveItem/content/read` | `content` is the property read when initiating a download | - | `initiate_file_upload` | `libre.graph/driveItem/upload/create` | `uploads` are a separate property. postprocessing creates the `content` | - | `add_grant` | `libre.graph/driveItem/permissions/create` | | - | `list_grant` | `libre.graph/driveItem/permissions/read` | | - | `update_grant` | `libre.graph/driveItem/permissions/update` | | - | `remove_grant` | `libre.graph/driveItem/permissions/delete` | | - | `deny_grant` | `libre.graph/driveItem/permissions/deny` | uses a non CRUD action `deny` | - | `list_file_versions` | `libre.graph/driveItem/versions/read` | `versions` is a `driveItemVersion` collection | - | `restore_file_version` | `libre.graph/driveItem/versions/update` | the only `update` action is restore | - | `list_recycle` | `libre.graph/driveItem/deleted/read` | reading a driveItem `deleted` property implies listing | - | `restore_recycle_item` | `libre.graph/driveItem/deleted/update` | the only `update` action is restore | - | `purge_recycle` | `libre.graph/driveItem/deleted/delete` | allows purging deleted `driveItems` | - items: - type: string - value: - type: array - items: - $ref: '#/components/schemas/permission' - # maxItems: 100 - '@odata.count': - type: integer - description: The total number of permissions available, only present if the `count` query parameter is set to true. - #'@odata.nextLink': - # type: string - example: - '@libre.graph.permissions.roles.allowedValues': - - id: b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 - description: "Allows reading the shared file or folder" - displayName: Viewer - # we don't want to reproduce all the individual role permissions, that is what the /roleManagement/permissions/roleDefinitions endpoint is for - # to build a custom role - #rolePermissions: - # - allowedResourceActions: - # - libre.graph/driveItem/basic/read - # - libre.graph/driveItem/permissions/read - # - libre.graph/driveItem/upload/create - # condition: "exists @Resource.File" - '@libre.graph.weight': 1 - - id: fb6c3e19-e378-47e5-b277-9732f9de6e21 - description: "Allows reading and writing the shared file or folder" - displayName: Editor - #rolePermissions: - # - allowedResourceActions: - # - libre.graph/driveItem/standard/allTasks - # condition: "exists @Resource.File" - '@libre.graph.weight': 2 - - id: 312c0871-5ef7-4b3a-85b6-0e4074c64049 - description: "Allows managing a space" - displayName: Manager - #rolePermissions: - # - allowedResourceActions: - # - libre.graph/drive/standard/allTasks - # condition: "exists @Resource.File" - '@libre.graph.weight': 3 - - id: 4916f47e-66d5-49bb-9ac9-748ad00334b - description: "Allows creating new files" - displayName: File Drop - #rolePermissions: - # - allowedResourceActions: - # libre.graph/driveItem/upload/create - # condition: "exists @Resource.File" - '@libre.graph.weight': 4 - '@libre.graph.permissions.actions.allowedValues': [ - "libre.graph/driveItem/basic/read", - "libre.graph/driveItem/permissions/read", - "libre.graph/driveItem/upload/create", - "libre.graph/driveItem/standard/allTasks", - "libre.graph/driveItem/upload/create" - ] - - value: - - id: "67445fde-a647-4dd4-b015-fc5dafd2821d" - link: - type: "view" - webUrl: "https://cloud.example.org/s/fhGBMIkKFEHWysj" - - - id: "34646ab6-be32-43c9-89e6-987e0c237e9b" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - - id: "b470677e-a7f5-4304-8ef5-f5056a21fff1" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - grantedToV2: - - user: - id: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c" - displayName: "Marie Skłodowska Curie" - - id: "453b02be-4ec2-4e7d-b576-09fc153de812" - roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - expirationDateTime: "2018-07-15T14:00:00.000Z" - - id: "86765c0d-3905-444a-9b07-76201f8cf7df" - roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ] - grantedToV2: - - group: - id: "167cbee2-0518-455a-bfb2-031fe0621e5d" - displayName: "Philosophy Haters" - - id: "c42b5cbd-2d65-42cf-b0b6-fb6d2b762256" - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - '@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ] - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/items/{item-id}/permissions/{perm-id}': - get: - tags: - - drives.permissions - summary: Get sharing permission for a file or folder - operationId: GetPermission - description: | - Return the effective sharing permission for a particular permission resource. - - # TODO do we need to implement inherited permissions from the start? - # Effective permissions of an item can come from two sources: permissions set directly on the item itself or permissions that are inherited from the item's ancestors. - # - # Callers can differentiate if the permission is inherited or not by checking the `inheritedFrom` property. This property is an ItemReference resource referencing the ancestor that the permission is inherited from. - # - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - responses: - '200': - description: Retrieved resource - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - edit permission: - value: - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "write" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - patch: - tags: - - drives.permissions - summary: Update sharing permission - operationId: UpdatePermission - description: | - Update the properties of a sharing permission by patching the permission resource. - - Only the `roles`, `expirationDateTime` and `password` properties can be modified this way. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - #- name: If-Match - # in: header - # description: | - # If this request header is included and the eTag (or cTag) provided does not match the current tag on the item, - # a `412 Precondition Failed`` response is returned and the item will not be updated. - # schema: - # type: string - requestBody: - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - update link: - description: Updating a public link is done by setting the `type` property of the permission link. - value: - link: - type: edit - update invite: - description: Updating an invite is done by setting the `roles` property of the permission. - value: - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - required: true - responses: - '200': - description: Updated permission - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - update link: - value: - id: "a373c812-d786-42ae-a65f-ed87ee4abd49" - link: - type: "edit" - webUrl: "https://cloud.example.org/s/MlnTDkhcBlihNzO" - update invite: - value: - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ] - expirationDateTime: "2018-07-15T14:00:00.000Z" - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - delete: - tags: - - drives.permissions - summary: Remove access to a DriveItem - operationId: DeletePermission - description: | - Remove access to a DriveItem. - - Only sharing permissions that are not inherited can be deleted. The `inheritedFrom` property must be `null`. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - #- name: If-Match - # in: header - # description: | - # If this request header is included and the eTag (or cTag) provided does not match the current tag on the item, - # a `412 Precondition Failed`` response is returned and the item will not be updated. - # schema: - # type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1beta1/drives/{drive-id}/items/{item-id}/permissions/{perm-id}/setPassword': - post: - tags: - - drives.permissions - summary: Set sharing link password - operationId: SetPermissionPassword - description: | - Set the password of a sharing permission. - - Only the `password` property can be modified this way. - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - - name: perm-id - in: path - description: 'key: id of permission' - required: true - schema: - type: string - x-ms-docs-key-type: permission - #- name: If-Match - # in: header - # description: | - # If this request header is included and the eTag (or cTag) provided does not match the current tag on the item, - # a `412 Precondition Failed`` response is returned and the item will not be updated. - # schema: - # type: string - requestBody: - description: New password value - content: - application/json: - schema: - $ref: '#/components/schemas/sharingLinkPassword' - examples: - set password: - value: - password: "TestPassword123!" - set empty password: - value: - password: "" - required: true - responses: - '200': - description: Updated permission - content: - application/json: - schema: - $ref: '#/components/schemas/permission' - examples: - set password on editor link with custom display name: - value: - - id: "7181275c-557e-4adf-8e44-abdcf5389b6a" - hasPassword: true - expirationDateTime: "2018-07-15T14:00:00.000Z" - link: - type: "edit" - displayName: "Homework" - webUrl: "https://cloud.example.org/s/fdleMyGeerkIZTJ" - set empty password: - value: - - id: "765c9b7b-6ccf-46ff-a659-95501250229c" - hasPassword: false - link: - type: "view" - displayName: "Quick link" - quicklink: true - webUrl: "https://cloud.example.org/s/erjHgjKjkstTesG" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/drives/{drive-id}/root': - get: - tags: - - drives.root - summary: Get root from arbitrary space - operationId: GetRoot - parameters: - - name: drive-id - in: path - description: 'key: id of drive' - required: true - schema: - type: string - x-ms-docs-key-type: drive - responses: - '200': - description: Retrieved resource - content: - application/json: - schema: - $ref: '#/components/schemas/driveItem' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1.0/groups: - get: - tags: - - groups - summary: Get entities from groups - operationId: ListGroups - parameters: - - $ref: '#/components/parameters/search' - - name: $orderby - in: query - description: Order items by property values - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - displayName - - displayName desc - type: string - - name: $select - in: query - description: Select properties to be returned - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - id - - description - - displayName - - mail - - members - type: string - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - members - type: string - responses: - '200': - description: Retrieved entities - content: - application/json: - schema: - title: Collection of group - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/group' - '@odata.nextLink': - type: string - default: - $ref: '#/components/responses/error' - x-ms-pageable: - nextLinkName: '@odata.nextLink' - operationName: listMore - x-ms-docs-operation-type: operation - post: - tags: - - groups - summary: Add new entity to groups - operationId: CreateGroup - requestBody: - description: New entity - content: - application/json: - schema: - $ref: '#/components/schemas/group' - required: true - responses: - '201': - description: Created entity - content: - application/json: - schema: - $ref: '#/components/schemas/group' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/groups/{group-id}': - get: - tags: - - group - summary: Get entity from groups by key - operationId: GetGroup - parameters: - - name: group-id - in: path - description: 'key: id or name of group' - required: true - schema: - type: string - x-ms-docs-key-type: group - - name: $select - in: query - description: Select properties to be returned - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - id - - description - - displayName - - members - type: string - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - members - type: string - responses: - '200': - description: Retrieved entity - content: - application/json: - schema: - $ref: '#/components/schemas/group' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - patch: - tags: - - group - summary: Update entity in groups - operationId: UpdateGroup - parameters: - - name: group-id - in: path - description: 'key: id of group' - required: true - schema: - type: string - x-ms-docs-key-type: group - requestBody: - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/group' - examples: - update name: - value: - displayName: GroupName - add multiple members: - value: - '@members@odata.bind': - - "https://localhost:9200/graph/v1.0/users/4c510ada-c86b-4815-8820-42cdf82c3d51" - - "https://localhost:9200/graph/v1.0/users/c54b0588-7157-4521-bb52-c1c8ca84ea71" - required: true - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - delete: - tags: - - group - summary: Delete entity from groups - operationId: DeleteGroup - parameters: - - name: group-id - in: path - description: 'key: id of group' - required: true - schema: - type: string - x-ms-docs-key-type: group - - name: If-Match - in: header - description: ETag - schema: - type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/groups/{group-id}/members': - get: - tags: - - group - summary: Get a list of the group's direct members - operationId: ListMembers - parameters: - - name: group-id - in: path - description: 'key: id or name of group' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - responses: - '200': - description: Retrieved group members - content: - application/json: - schema: - title: Collection of users - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/user' - example: - - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - onPremisesSAMAccountName: max.mustermann - displayName: Max Mustermann - mail: max.musterman@example.org - default: - $ref: '#/components/responses/error' - '/v1.0/groups/{group-id}/members/$ref': - post: - tags: - - group - summary: Add a member to a group - operationId: AddMember - parameters: - - name: group-id - in: path - description: 'key: id of group' - required: true - schema: - type: string - x-ms-docs-key-type: group - requestBody: - description: Object to be added as member - content: - application/json: - schema: - title: Member Reference - type: object - properties: - '@odata.id': - type: string - required: true - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/groups/{group-id}/members/{directory-object-id}/$ref': - delete: - tags: - - group - summary: Delete member from a group - operationId: DeleteMember - parameters: - - name: group-id - in: path - description: 'key: id of group' - required: true - schema: - type: string - x-ms-docs-key-type: group - - name: directory-object-id - in: path - description: 'key: id of group member to remove' - required: true - schema: - type: string - - name: If-Match - in: header - description: ETag - schema: - type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1.0/me/drive: - get: - tags: - - me.drive - summary: Get personal space for user - operationId: GetHome - responses: - '200': - description: Retrieved personal space - content: - application/json: - schema: - $ref: '#/components/schemas/drive' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1.0/me/drive/root: - get: - tags: - - me.drive.root - summary: Get root from personal space - operationId: HomeGetRoot - responses: - '200': - description: Retrieved resource - content: - application/json: - schema: - $ref: '#/components/schemas/driveItem' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1.0/me/drive/root/children: - get: - tags: - - me.drive.root.children - summary: Get children from drive - operationId: HomeGetChildren - responses: - '200': - description: Retrieved resource list - content: - application/json: - schema: - title: Collection of driveItems - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/driveItem' - maxItems: 100 - '@odata.nextLink': - type: string - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1beta1/me/drive/sharedByMe: - get: - tags: - - me.drive - summary: Get a list of driveItem objects shared by the current user. - operationId: ListSharedByMe - description: | - The `driveItems` returned from the `sharedByMe` method always include the `permissions` relation that indicates they are shared items. - parameters: - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - thumbnails - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - title: Collection of driveItems - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/driveItem' - # maxItems: 20 - #'@odata.nextLink': - # type: string - example: - value: - - id: 78363031-03ef-4eda-84a2-243a691a13cd - createdDateTime: "2020-02-19T14:23:25.52Z" - # not yet supported by opencloud - #cTag: "adDpDMTI2NDRBMTRCMEE3NzUwITEzNzkuNjM3NjYyNzQ5NjU1MDMwMDAw" - eTag: "aQzEyNjQ0QTE0QjBBNzc1MCExMzc5LjQ" - lastModifiedDateTime: "2021-09-03T14:09:25.503Z" - name: "March Proposal.docx" - parentReference: - driveId: "1991210caf" - driveType: personal - permissions: - - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "write" ] - grantedToV2: - - user: - id: "4c510ada-c86b-4815-8820-42cdf82c3d51" - displayName: "Albert Einstein" - - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474" - roles: [ "read" ] - grantedToV2: - - user: - id: "48016357-346a-443e-bf7a-945c9448a99b" - displayName: "Marie Curie" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - /v1.0/me/drive/items/{item-id}/follow: - post: - tags: - - me.drive - summary: Follow a DriveItem - description: Follow a DriveItem. - operationId: FollowDriveItem - parameters: - - name: item-id - in: path - description: 'key: id of item' - required: true - schema: - type: string - x-ms-docs-key-type: item - responses: - "201": - description: Created - content: - application/json: - schema: - $ref: "#/components/schemas/driveItem" - default: - $ref: "#/components/responses/error" - x-ms-docs-operation-type: operation - /v1.0/me/drive/following/{item-id}: - delete: - tags: - - me.drive - summary: Unfollow a DriveItem - description: Unfollow a DriveItem. - operationId: UnfollowDriveItem - parameters: - - name: item-id - in: path - description: "key: id of item" - required: true - schema: - type: string - x-ms-docs-key-type: item - responses: - "204": - description: No Content - default: - $ref: "#/components/responses/error" - x-ms-docs-operation-type: operation - - /v1beta1/me/drive/sharedWithMe: - get: - tags: - - me.drive - summary: Get a list of driveItem objects shared with the owner of a drive. - operationId: ListSharedWithMe - description: | - The `driveItems` returned from the `sharedWithMe` method always include the `remoteItem` facet that indicates they are items from a different drive. - parameters: - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - thumbnails - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - title: Collection of driveItems - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/driveItem' - # maxItems: 20 - #'@odata.nextLink': - # type: string - example: - value: - - id: 78363031-03ef-4eda-84a2-243a691a13cd - '@UI.hidden': false - '@client.synchronize': true - createdBy: - user: - displayName: "Albert Einstein" - id: "44feab10d55e9871" - cTag: "adDpDMTI2NDRBMTRCMEE3NzUwITEzNzkuNjM3NjYyNzQ5NjU1MDMwMDAw" - eTag: "aQzEyNjQ0QTE0QjBBNzc1MCExMzc5LjQ" - lastModifiedDateTime: "2021-09-03T14:09:25.503Z" - name: "March Proposal.docx" - parentReference: - driveId: "1991210caf" - driveType: personal - remoteItem: - id: 02d7a7df-a6f7-44cc-848a-3c98f7dd5046 - name: "March Proposal.docx" - size: 19121 - lastModifiedDateTime: "2021-09-03T14:09:25.503Z" - permissions: - - id: 7310e99f-377b-4cba-a1f0-ffa3331fd32c - roles: - - b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 - grantedToV2: - group: - displayName: "users" - id: 509a9dcd-bb37-4f4f-a01a-19dca27d9cfa - invitation: - invitedBy: - user: - displayName: "Albert Einstein" - id: "44feab10d55e9871" - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - - /v1.0/invitations: - post: - tags: - - invitations - summary: Create a new invitation - operationId: CreateInvitation - requestBody: - description: New invitation - content: - application/json: - schema: - $ref: '#/components/schemas/invitation' - responses: - '201': - description: Invitation created successfully - content: - application/json: - schema: - $ref: '#/components/schemas/invitation' - x-ms-docs-operation-type: operation - get: - tags: - - invitations - summary: Get a list of invitations - operationId: ListInvitations - responses: - '200': - description: Retrieved invitations - content: - application/json: - schema: - title: Collection of invitations - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/invitation' - - /v1.0/invitations/{invitation-id}: - get: - tags: - - invitations - summary: Get an invitation by key - operationId: GetInvitation - parameters: - - name: invitation-id - in: path - description: 'key: id of invitation' - required: true - schema: - type: string - responses: - '200': - description: Retrieved invitation - content: - application/json: - schema: - $ref: '#/components/schemas/invitation' - - /v1.0/users: - get: - tags: - - users - summary: Get entities from users - operationId: ListUsers - parameters: - - $ref: '#/components/parameters/search' - - $ref: '#/components/parameters/usersFilter' - - name: $orderby - in: query - description: Order items by property values - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - displayName - - displayName desc - - mail - - mail desc - - onPremisesSamAccountName - - onPremisesSamAccountName desc - type: string - - name: $select - in: query - description: Select properties to be returned - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - id - - displayName - - mail - - memberOf - - onPremisesSamAccountName - - surname - type: string - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - drive - - drives - - memberOf - - appRoleAssignments - type: string - responses: - '200': - description: Retrieved entities - content: - application/json: - schema: - title: Collection of user - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/user' - '@odata.nextLink': - type: string - default: - $ref: '#/components/responses/error' - x-ms-pageable: - nextLinkName: '@odata.nextLink' - operationName: listMore - x-ms-docs-operation-type: operation - post: - tags: - - users - summary: Add new entity to users - operationId: CreateUser - requestBody: - description: New entity - content: - application/json: - schema: - $ref: '#/components/schemas/user' - required: true - responses: - '201': - description: Created entity - content: - application/json: - schema: - $ref: '#/components/schemas/user' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/users/{user-id}': - get: - tags: - - user - summary: Get entity from users by key - operationId: GetUser - parameters: - - name: user-id - in: path - description: 'key: id or name of user' - required: true - schema: - type: string - x-ms-docs-key-type: user - - name: $select - in: query - description: Select properties to be returned - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - id - - displayName - - drive - - drives - - mail - - memberOf - - onPremisesSamAccountName - - surname - type: string - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - drive - - drives - - memberOf - - appRoleAssignments - type: string - responses: - '200': - description: Retrieved entity - content: - application/json: - schema: - $ref: '#/components/schemas/user' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - patch: - tags: - - user - summary: Update entity in users - operationId: UpdateUser - parameters: - - name: user-id - in: path - description: 'key: id of user' - required: true - schema: - type: string - x-ms-docs-key-type: user - requestBody: - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/userUpdate' - examples: - change displayName: - value: - displayName: "Marie Skłodowska Curie" - change email: - value: - mail: "marie@example.com" - change preferred language: - value: - preferredLanguage: "fr" - required: true - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/user' - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - delete: - tags: - - user - summary: Delete entity from users - operationId: DeleteUser - parameters: - - name: user-id - in: path - description: 'key: id or name of user' - required: true - schema: - type: string - x-ms-docs-key-type: user - - name: If-Match - in: header - description: ETag - schema: - type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/users/{user-id}/exportPersonalData': - post: - tags: - - user - summary: export personal data of a user - operationId: ExportPersonalData - parameters: - - name: user-id - in: path - description: 'key: id or name of user' - required: true - schema: - type: string - x-ms-docs-key-type: user - requestBody: - description: destination the file should be created at - content: - application/json: - schema: - properties: - storageLocation: - type: string - description: the path where the file should be created in the users personal space - responses: - 202: - description: success - default: - $ref: '#/components/responses/error' - x-ms-docs-operation-type: operation - '/v1.0/users/{user-id}/appRoleAssignments': - description: Provides operations to manage assignments of roles to users. - get: - tags: - - user.appRoleAssignment - summary: Get appRoleAssignments from a user - description: Represents the global roles a user has been granted for an application. - operationId: user.ListAppRoleAssignments - responses: - 200: - description: Retrieved appRoleAssignments - content: - application/json: - schema: - title: Collection of appRoleAssignments - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/appRoleAssignment' - maxItems: 100 - '@odata.nextLink': - type: string - default: - $ref: '#/components/responses/error' - post: - tags: - - user.appRoleAssignment - summary: Grant an appRoleAssignment to a user - description: | - Use this API to assign a global role to a user. To grant an app role assignment to a user, you need three identifiers: - * `principalId`: The `id` of the user to whom you are assigning the app role. - * `resourceId`: The `id` of the resource `servicePrincipal` or `application` that has defined the app role. - * `appRoleId`: The `id` of the `appRole` (defined on the resource service principal or application) to assign to the user. - operationId: user.CreateAppRoleAssignments - requestBody: - description: New app role assignment value - content: - application/json: - schema: - $ref: '#/components/schemas/appRoleAssignment' - required: true - responses: - 200: - description: Created new app role assignment. - content: - application/json: - schema: - $ref: '#/components/schemas/appRoleAssignment' - default: - $ref: '#/components/responses/error' - parameters: - - name: user-id - in: path - description: 'key: id of user' - required: true - style: simple - schema: - type: string - '/v1.0/users/{user-id}/appRoleAssignments/{appRoleAssignment-id}': - description: Provides operations to manage a global role for an assigned user. - delete: - tags: - - user.appRoleAssignment - summary: Delete the appRoleAssignment from a user - operationId: user.DeleteAppRoleAssignments - parameters: - - name: If-Match - in: header - description: ETag - style: simple - schema: - type: string - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - parameters: - - name: user-id - in: path - description: 'key: id of user' - required: true - style: simple - schema: - type: string - - name: appRoleAssignment-id - in: path - description: 'key: id of appRoleAssignment. This is the concatenated {user-id}:{appRole-id} separated by a colon.' - required: true - style: simple - schema: - type: string - '/v1.0/users/{user-id}/photo/$value': - get: - tags: - - user.photo - summary: Get the photo of a user - operationId: GetUserPhoto - parameters: - - name: user-id - in: path - description: 'key: id or name of user' - required: true - schema: - type: string - x-ms-docs-key-type: user - responses: - '200': - description: Retrieved photo - content: - image/jpeg: - schema: - type: string - format: binary - default: - $ref: '#/components/responses/error' - /v1.0/education/users: - get: - tags: - - educationUser - summary: Get entities from education users - description: | - Retrieves a collection of education users with optional filtering, ordering, and expansion. - - **Filtering by external ID:** - Use `$filter` to query users by their external identifier, for example: - `$filter=externalId eq 'EX12345'` - security: - - bearerAuth: [ ] - operationId: ListEducationUsers - parameters: - - name: $filter - in: query - description: | - Filter items by property values. Supports a subset of OData filter expressions. - - **Supported filters:** - - By external ID: `externalId eq 'ext_12345'` - schema: - type: string - examples: - externalId: - value: externalId eq 'ext_12345' - summary: Filter by external ID - - name: $orderby - in: query - description: Order items by property values - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - displayName - - displayName desc - - mail - - mail desc - - onPremisesSamAccountName - - onPremisesSamAccountName desc - type: string - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - memberOf - type: string - responses: - '200': - description: Retrieved entities - content: - application/json: - schema: - title: Collection of educationUser - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/educationUser' - example: - - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - onPremisesSAMAccountName: max.mustermann - displayName: Max Mustermann - mail: max.musterman@example.org - primaryRole: student - identities: - - issuer: idp.school.com - issuerAssignedId: max.mustermann - - issuer: newidp.school.com - issuerAssignedId: ieZ2AeV5 - default: - $ref: '#/components/responses/error' - post: - tags: - - educationUser - summary: Add new education user - security: - - bearerAuth: [ ] - operationId: CreateEducationUser - requestBody: - description: New entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationUser' - examples: - student: - $ref: '#/components/examples/educationUser_post' - externalId: - $ref: '#/components/examples/educationUser_post_externalId' - required: true - responses: - '201': - description: Created entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationUser' - examples: - student: - $ref: '#/components/examples/educationUser' - default: - $ref: '#/components/responses/error' - '/v1.0/education/users/{user-id}': - get: - tags: - - educationUser - summary: Get properties of educationUser - security: - - bearerAuth: [ ] - operationId: GetEducationUser - parameters: - - name: user-id - in: path - description: 'key: id or username of user' - required: true - schema: - type: string - examples: - id: - value: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - name: - value: max.mustermann - - name: $expand - in: query - description: Expand related entities - style: form - explode: false - schema: - uniqueItems: true - type: array - items: - enum: - - memberOf - type: string - responses: - '200': - description: Retrieved entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationUser' - examples: - student: - $ref: '#/components/examples/educationUser' - default: - $ref: '#/components/responses/error' - patch: - tags: - - educationUser - summary: Update properties of educationUser - security: - - bearerAuth: [ ] - operationId: UpdateEducationUser - parameters: - - name: user-id - in: path - description: 'key: id or username of user' - required: true - schema: - type: string - example: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - requestBody: - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/educationUser' - example: - mail: max.mustermann@new.domain - required: true - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/educationUser' - example: - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - onPremisesSAMAccountName: max.mustermann - displayName: Max Mustermann - surname: Mustermann - givenName: Max - mail: max.musterman@new.domain - primaryRole: student - identities: - - issuer: idp.school.com - issuerAssignedId: max.mustermann - '204': - description: Success - default: - $ref: '#/components/responses/error' - delete: - tags: - - educationUser - summary: Delete educationUser - description: | - Deletes an education user by their internal ID. - - **To delete by external ID:** - If you only have an external ID, you must first retrieve the user's internal ID: - 1. Call `GET /graph/v1.0/education/users?$filter=externalId eq '{value}'` - 2. Extract the `id` from the response - 3. Use that `id` in this DELETE endpoint - - See the [ListEducationUsers](#/educationUser/ListEducationUsers) operation for query details. - security: - - bearerAuth: [ ] - operationId: DeleteEducationUser - parameters: - - name: user-id - in: path - description: | - key: internal user id (UUID format) or username of user. - - **Note:** If you only have an external ID, first query the user - with `GET /graph/v1.0/education/users?$filter=externalId eq '{value}'` - to retrieve the internal ID. - required: true - schema: - type: string - example: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - responses: - '204': - description: Success - '404': - description: User not found - default: - $ref: '#/components/responses/error' - /v1.0/education/schools: - get: - tags: - - educationSchool - summary: Get a list of schools and their properties - description: | - Retrieves a collection of education schools with optional filtering and ordering. - - **Filtering by external ID:** - Use `$filter` to query schools by their external identifier, for example: - `$filter=externalId eq 'EX12345'` - security: - - bearerAuth: [ ] - operationId: ListSchools - parameters: - - name: $filter - in: query - description: | - Filter items by property values. Supports a subset of OData filter expressions. - - **Supported filters:** - - By external ID: `externalId eq 'ext_12345'` - schema: - type: string - examples: - externalId: - value: externalId eq 'ext_12345' - summary: Filter by external ID - responses: - '200': - description: Retrieved entities - content: - application/json: - schema: - title: Collection of schools - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/educationSchool' - example: - - id: 0e19303e-8144-44bd-86d8-35cc8ac9c255 - displayName: Gymnasium Musterstadt - schoolNumber: '0123' - terminationDate: 2023-06-30T00:00:00Z - - id: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - displayName: Realschule Musterstadt - schoolNumber: '1234' - default: - $ref: '#/components/responses/error' - post: - tags: - - educationSchool - summary: Add new school - security: - - bearerAuth: [ ] - operationId: CreateSchool - requestBody: - description: New school - content: - application/json: - schema: - $ref: '#/components/schemas/educationSchool' - examples: - school: - $ref: '#/components/examples/educationSchool_post' - required: true - responses: - '201': - description: Created entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationSchool' - examples: - school: - $ref: '#/components/examples/educationSchool' - default: - $ref: '#/components/responses/error' - '/v1.0/education/schools/{school-id}': - get: - tags: - - educationSchool - summary: Get the properties of a specific school - security: - - bearerAuth: [ ] - operationId: GetSchool - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - responses: - '200': - description: Retrieved entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationSchool' - examples: - school: - $ref: '#/components/examples/educationSchool' - default: - $ref: '#/components/responses/error' - patch: - tags: - - educationSchool - summary: Update properties of a school - security: - - bearerAuth: [ ] - operationId: UpdateSchool - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - requestBody: - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/educationSchool' - examples: - schoolNumber: - $ref: '#/components/examples/educationSchool_patchNumber' - schoolTerminationDate: - $ref: '#/components/examples/educationSchool_patchTerminationDate' - deleteSchoolTerminationDate: - $ref: '#/components/examples/educationSchool_deleteTerminationDate' - required: true - responses: - '200': - description: Success - content: - application/json: - schema: - $ref: '#/components/schemas/educationSchool' - examples: - school: - $ref: '#/components/examples/educationSchool' - default: - $ref: '#/components/responses/error' - delete: - tags: - - educationSchool - summary: Delete school - description: Deletes a school. A school can only be delete if it has the terminationDate property set. And if that termination Date is in the past. - security: - - bearerAuth: [ ] - operationId: DeleteSchool - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/schools/{school-id}/users': - get: - tags: - - educationSchool - summary: Get the educationUser resources associated with an educationSchool - security: - - bearerAuth: [ ] - operationId: ListSchoolUsers - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - responses: - '200': - description: Retrieved educationUser - content: - application/json: - schema: - title: Collection of educationUser - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/educationUser' - example: - - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - onPremisesSAMAccountName: max.mustermann - displayName: Max Mustermann - surname: Mustermann - givenName: Max - mail: max.musterman@example.org - primaryRole: student - identities: - - issuer: idp.school.com - issuerAssignedId: max.mustermann - default: - $ref: '#/components/responses/error' - '/v1.0/education/schools/{school-id}/users/$ref': - post: - tags: - - educationSchool - summary: Assign a user to a school - security: - - bearerAuth: [ ] - operationId: AddUserToSchool - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - requestBody: - description: educationUser to be added as member - content: - application/json: - schema: - title: EducationUser Reference - type: object - properties: - '@odata.id': - type: string - example: "https:///graph/v1.0/education/users/90eedea1-dea1-90ee-a1de-ee90a1deee90" - required: true - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/schools/{school-id}/users/{user-id}/$ref': - delete: - tags: - - educationSchool - summary: Unassign user from a school - security: - - bearerAuth: [ ] - operationId: DeleteUserFromSchool - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - - name: user-id - in: path - description: 'key: id or username of the user to unassign from school' - required: true - schema: - type: string - example: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/schools/{school-id}/classes': - get: - tags: - - educationSchool - summary: Get the educationClass resources owned by an educationSchool - security: - - bearerAuth: [ ] - operationId: ListSchoolClasses - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - responses: - '200': - description: Retrieved classes - content: - application/json: - schema: - title: Collection of educationClass - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/educationClass' - example: - - id: 86948e45-96a6-43df-b83d-46e92afd30de - displayName: Mathematik - classification: course - externalId: ac528aea-978e-415c-a733-c4ba235d3388 - - id: 9097631c-24b6-4621-9635-36195a9c8d79 - displayName: 10b - classification: class - externalId: 0123_10b - default: - $ref: '#/components/responses/error' - '/v1.0/education/schools/{school-id}/classes/$ref': - post: - tags: - - educationSchool - summary: Assign a class to a school - security: - - bearerAuth: [ ] - operationId: AddClassToSchool - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - requestBody: - description: educationClass to be added as member - content: - application/json: - schema: - title: Class Reference - type: object - properties: - '@odata.id': - type: string - example: "https:///graph/v1.0/education/classes/7e84a069-f374-479b-817d-71590117d443" - required: true - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/schools/{school-id}/classes/{class-id}/$ref': - delete: - tags: - - educationSchool - summary: Unassign class from a school - security: - - bearerAuth: [ ] - operationId: DeleteClassFromSchool - parameters: - - name: school-id - in: path - description: 'key: id or schoolNumber of school' - required: true - schema: - type: string - example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4 - - name: class-id - in: path - description: 'key: id or externalId of the class to unassign from school' - required: true - schema: - type: string - example: 7e84a069-f374-479b-817d-71590117d443 - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - /v1.0/education/classes: - get: - tags: - - educationClass - summary: list education classes - operationId: ListClasses - security: - - bearerAuth: [ ] - responses: - '200': - description: Retrieved entities - content: - application/json: - schema: - title: Collection of class - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/educationClass' - example: - - id: 86948e45-96a6-43df-b83d-46e92afd30de - displayName: Mathematik - classification: course - externalId: ac528aea-978e-415c-a733-c4ba235d3388 - - id: 9097631c-24b6-4621-9635-36195a9c8d79 - displayName: 10b - classification: class - externalId: 0123_10b - default: - $ref: '#/components/responses/error' - post: - tags: - - educationClass - summary: Add new education class - security: - - bearerAuth: [ ] - operationId: CreateClass - requestBody: - description: New entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationClass' - examples: - class: - $ref: '#/components/examples/educationClass_post' - required: true - responses: - '201': - description: Created entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationClass' - examples: - class: - $ref: '#/components/examples/educationClass' - default: - $ref: '#/components/responses/error' - '/v1.0/education/classes/{class-id}': - get: - tags: - - educationClass - summary: Get class by key - security: - - bearerAuth: [ ] - operationId: GetClass - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - responses: - '200': - description: Retrieved entity - content: - application/json: - schema: - $ref: '#/components/schemas/educationClass' - examples: - class: - $ref: '#/components/examples/educationClass' - default: - $ref: '#/components/responses/error' - patch: - tags: - - educationClass - summary: Update properties of a education class - security: - - bearerAuth: [ ] - operationId: UpdateClass - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - requestBody: - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/educationClass' - examples: - update name: - value: - displayName: Musik - add multiple members: - value: - '@members@odata.bind': - - "https://localhost:9200/graph/v1.0/education/users/4c510ada-c86b-4815-8820-42cdf82c3d51" - - "https://localhost:9200/graph/v1.0/education/users/c54b0588-7157-4521-bb52-c1c8ca84ea71" - required: true - responses: - '200': - description: New property values - content: - application/json: - schema: - $ref: '#/components/schemas/educationClass' - example: - id: 86948e45-96a6-43df-b83d-46e92afd30de - displayName: Musik - classification: course - externalId: cb766da3-bab1-478a-9615-f99d4c59c09a - '204': - description: Success - default: - $ref: '#/components/responses/error' - delete: - tags: - - educationClass - summary: Delete education class - security: - - bearerAuth: [ ] - operationId: DeleteClass - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/classes/{class-id}/members': - get: - tags: - - educationClass - summary: Get the educationClass resources owned by an educationSchool - security: - - bearerAuth: [ ] - operationId: ListClassMembers - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - responses: - '200': - description: Retrieved class members - content: - application/json: - schema: - title: Collection of educationUser - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/educationUser' - example: - - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - onPremisesSAMAccountName: max.mustermann - displayName: Max Mustermann - surname: Mustermann - givenName: Max - mail: max.musterman@example.org - primaryRole: student - identities: - - issuer: idp.school.com - issuerAssignedId: max.mustermann - default: - $ref: '#/components/responses/error' - '/v1.0/education/classes/{class-id}/members/$ref': - post: - tags: - - educationClass - summary: Assign a user to a class - security: - - bearerAuth: [ ] - operationId: AddUserToClass - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - requestBody: - description: educationUser to be added as member - content: - application/json: - schema: - title: Class Member Reference - type: object - properties: - '@odata.id': - type: string - example: "https:///graph/v1.0/education/users/90eedea1-dea1-90ee-a1de-ee90a1deee90" - required: true - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/classes/{class-id}/members/{user-id}/$ref': - delete: - tags: - - educationClass - summary: Unassign user from a class - security: - - bearerAuth: [ ] - operationId: DeleteUserFromClass - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - - name: user-id - in: path - description: 'key: id or username of the user to unassign from class' - required: true - schema: - type: string - example: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/classes/{class-id}/teachers': - get: - tags: - - educationClass.teachers - summary: Get the teachers for a class - security: - - bearerAuth: [ ] - operationId: GetTeachers - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - responses: - '200': - description: Retrieved class teachers - content: - application/json: - schema: - title: Collection of educationUser - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/educationUser' - example: - - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - onPremisesSAMAccountName: max.mustermann - displayName: Max Mustermann - surname: Mustermann - givenName: Max - mail: max.musterman@example.org - primaryRole: teacher - identities: - - issuer: idp.school.com - issuerAssignedId: max.mustermann - default: - $ref: '#/components/responses/error' - '/v1.0/education/classes/{class-id}/teachers/$ref': - post: - tags: - - educationClass.teachers - summary: Assign a teacher to a class - security: - - bearerAuth: [ ] - operationId: AddTeacherToClass - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - example: 86948e45-96a6-43df-b83d-46e92afd30de - requestBody: - description: educationUser to be added as teacher - content: - application/json: - schema: - title: Class Teacher Reference - type: object - properties: - '@odata.id': - type: string - example: "https:///graph/v1.0/education/users/90eedea1-dea1-90ee-a1de-ee90a1deee90" - required: true - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/education/classes/{class-id}/teachers/{user-id}/$ref': - delete: - tags: - - educationClass.teachers - summary: Unassign user as teacher of a class - security: - - bearerAuth: [ ] - operationId: DeleteTeacherFromClass - parameters: - - name: class-id - in: path - description: 'key: id or externalId of class' - required: true - schema: - type: string - - name: user-id - in: path - description: 'key: id or username of the user to unassign as teacher' - required: true - schema: - type: string - example: 90eedea1-dea1-90ee-a1de-ee90a1deee90 - responses: - '204': - description: Success - default: - $ref: '#/components/responses/error' - '/v1.0/extensions/org.libregraph/tags': - get: - tags: - - tags - summary: Get all known tags - operationId: GetTags - responses: - '200': - description: Retrieved tags - content: - application/json: - schema: - title: Collection of tags - type: object - properties: - value: - type: array - items: - type: string - default: - $ref: '#/components/responses/error' - put: - tags: - - tags - summary: Assign tags to a resource - operationId: AssignTags - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/tagAssignment' - examples: - assign: - $ref: '#/components/examples/tags_put' - responses: - '200': - description: No content - default: - $ref: '#/components/responses/error' - delete: - tags: - - tags - summary: Unassign tags from a resource - operationId: UnassignTags - requestBody: - content: - application/json: - schema: - $ref: '#/components/schemas/tagUnassignment' - examples: - unassign: - $ref: '#/components/examples/tags_delete' - responses: - '200': - description: No content - default: - $ref: '#/components/responses/error' - /v1.0/applications: - get: - tags: - - applications - summary: Get all applications - operationId: ListApplications - responses: - '200': - description: Retrieved entities - content: - application/json: - schema: - title: Collection of applications - type: object - properties: - value: - type: array - items: - $ref: '#/components/schemas/application' - default: - $ref: '#/components/responses/error' - /v1.0/applications/{application-id}: - get: - tags: - - applications - summary: Get application by id - operationId: GetApplication - parameters: - - name: application-id - in: path - description: 'key: id of application' - required: true - schema: - type: string - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/application' - default: - $ref: '#/components/responses/error' - /v1beta1/roleManagement/permissions/roleDefinitions: - get: - tags: - - roleManagement - summary: List roleDefinitions - operationId: ListPermissionRoleDefinitions - description: | - Get a list of `unifiedRoleDefinition` objects for the permissions provider. This list determines the roles that can be selected when creating sharing invites. - responses: - '200': - description: A list of permission roles than can be used when sharing with users or groups. - content: - application/json: - schema: - type: array - items: - $ref: '#/components/schemas/unifiedRoleDefinition' - example: - - id: b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 - description: "Allows reading the shared file or folder" - displayName: Viewer - rolePermissions: - - allowedResourceActions: - - libre.graph/driveItem/basic/read - - libre.graph/driveItem/permissions/read - - libre.graph/driveItem/upload/create - condition: "exists @Resource.File" - '@libre.graph.weight': 1 - - id: fb6c3e19-e378-47e5-b277-9732f9de6e21 - description: "Allows reading and writing the shared file or folder" - displayName: Editor - rolePermissions: - - allowedResourceActions: - - libre.graph/driveItem/standard/allTasks - condition: "exists @Resource.File" - '@libre.graph.weight': 2 - - id: 312c0871-5ef7-4b3a-85b6-0e4074c64049 - description: "Allows managing a space" - displayName: Manager - rolePermissions: - - allowedResourceActions: - - libre.graph/drive/standard/allTasks - condition: "exists @Resource.File" - '@libre.graph.weight': 3 - - id: 4916f47e-66d5-49bb-9ac9-748ad00334b - description: "Allows creating new files" - displayName: File Drop - rolePermissions: - - allowedResourceActions: - - libre.graph/driveItem/upload/create - condition: "exists @Resource.File" - '@libre.graph.weight': 4 - default: - $ref: '#/components/responses/error' - /v1beta1/roleManagement/permissions/roleDefinitions/{role-id}: - get: - tags: - - roleManagement - summary: Get unifiedRoleDefinition - operationId: GetPermissionRoleDefinition - description: | - Read the properties and relationships of a `unifiedRoleDefinition` object. - parameters: - - name: role-id - in: path - description: 'key: id of roleDefinition' - required: true - schema: - type: string - x-ms-docs-key-type: roleDefinition - responses: - '200': - description: OK - content: - application/json: - schema: - $ref: '#/components/schemas/unifiedRoleDefinition' - examples: - Viewer: - value: - id: b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5 - description: "Allows reading the shared file or folder" - displayName: Viewer - rolePermissions: - - allowedResourceActions: - - libre.graph/driveItem/basic/read - condition: "exists @Resource.File" - '@libre.graph.weight': 1 - Editor: - value: - id: fb6c3e19-e378-47e5-b277-9732f9de6e21 - description: "Allows reading and writing the shared file or folder" - displayName: Editor - rolePermissions: - - allowedResourceActions: - - libre.graph/driveItem/standard/allTasks - condition: "exists @Resource.File" - '@libre.graph.weight': 2 - Manager: - value: - id: 312c0871-5ef7-4b3a-85b6-0e4074c64049 - description: "Allows managing a space" - displayName: Manager - rolePermissions: - - allowedResourceActions: - - libre.graph/drive/standard/allTasks - condition: "exists @Resource.File" - '@libre.graph.weight': 3 - File Drop: - value: - id: 4916f47e-66d5-49bb-9ac9-748ad00334b - description: "Allows creating new files" - displayName: File Drop - rolePermissions: - - allowedResourceActions: - - libre.graph/driveItem/standard/create - condition: "exists @Resource.File" - '@libre.graph.weight': 4 - default: - $ref: '#/components/responses/error' -components: - schemas: - tagAssignment: - type: object - required: - - resourceId - - tags - properties: - resourceId: - type: string - tags: - type: array - items: - type: string - tagUnassignment: - type: object - required: - - resourceId - - tags - properties: - resourceId: - type: string - tags: - type: array - items: - type: string - educationSchool: - description: Represents a school - type: object - properties: - id: - type: string - description: The unique identifier for an entity. Read-only. - readOnly: true - displayName: - type: string - description: The organization name - schoolNumber: - type: string - description: School number - externalId: - type: string - description: External identifier of the school - terminationDate: - type: string - format: date-time - nullable: true - description: Date and time at which the service for this organization is scheduled to be terminated - educationClass: - description: And extension of group representing a class or course - type: object - required: - - displayName - - classification - properties: - # entity - id: - type: string - description: Read-only. - readOnly: true - # group - description: - type: string - description: 'An optional description for the group. Returned by default.' - displayName: - type: string - description: 'The display name for the group. This property is required when a group is created and cannot be cleared during updates. Returned by default. Supports $search and $orderBy.' - members: - type: array - items: - $ref: '#/components/schemas/user' - description: 'Users and groups that are members of this group. HTTP Methods: GET (supported for all groups), Nullable. Supports $expand.' - 'members@odata.bind': - type: array - items: - type: string - uniqueItems: true - minItems: 1 - maxItems: 20 - description: A list of member references to the members to be added. Up to 20 members can be added with a single request - classification: - type: string - enum: [ class, course ] - description: 'Classification of the group, i.e. "class" or "course"' - externalId: - type: string - description: An external unique ID for the class - educationUser: - description: An extension of user with education-specific attributes - type: object - properties: - # entity - id: - type: string - description: Read-only. - readOnly: true - # user - accountEnabled: - type: boolean - description: 'Set to "true" when the account is enabled.' - displayName: - type: string - description: 'The name displayed in the address book for the user. This value is usually the combination of the user''s first name, middle initial, and last name. This property is required when a user is created and it cannot be cleared during updates. Returned by default. Supports $orderby.' - drives: - type: array - items: - $ref: '#/components/schemas/drive' - description: A collection of drives available for this user. Read-only. - maxItems: 100 - readOnly: true - drive: - $ref: '#/components/schemas/drive' - description: The personal drive of this user. Read-only. - readOnly: true - externalId: - type: string - description: An external unique ID for the user. Use it to associate a user in another system, such as a student or employee ID number. - identities: - description: Identities associated with this account. - type: array - items: - $ref: '#/components/schemas/objectIdentity' - mail: - type: string - description: 'The SMTP address for the user, for example, ''jeff@contoso.opencloud.com''. Returned by default.' - memberOf: - type: array - items: - $ref: '#/components/schemas/group' - description: 'Groups that this user is a member of. HTTP Methods: GET (supported for all groups). Read-only. Nullable. Supports $expand.' - onPremisesSamAccountName: - type: string - description: 'Contains the on-premises SAM account name synchronized from the on-premises directory. Read-only.' - passwordProfile: - $ref: '#/components/schemas/passwordProfile' - surname: - type: string - description: The user's surname (family name or last name). Returned by default. - givenName: - type: string - description: The user's givenName. Returned by default. - primaryRole: - type: string - description: 'The user`s default role. Such as "student" or "teacher"' - userType: - type: string - description: 'The user`s type. This can be either "Member" for regular user, "Guest" for guest users or "Federated" for users imported from a federated instance.' - drive: - description: The drive represents a space on the storage. - required: - - name - allOf: - - $ref: '#/components/schemas/driveUpdate' - driveUpdate: - description: The drive represents an update to a space on the storage. - type: object - properties: - # entity - id: - type: string - description: The unique identifier for this drive. - readOnly: true - # base item - createdBy: - $ref: '#/components/schemas/identitySet' - description: 'Identity of the user, device, or application which created the item. Read-only.' - readOnly: true - createdDateTime: - pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$' - type: string - description: Date and time of item creation. Read-only. - format: date-time - readOnly: true - description: - type: string - description: Provides a user-visible description of the item. Optional. - eTag: - type: string - description: ETag for the item. Read-only. - readOnly: true - lastModifiedBy: - $ref: '#/components/schemas/identitySet' - description: 'Identity of the user, device, and application which last modified the item. Read-only.' - readOnly: true - lastModifiedDateTime: - pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$' - type: string - description: Date and time the item was last modified. Read-only. - format: date-time - readOnly: true - name: - type: string - description: The name of the item. Read-write. - parentReference: - $ref: '#/components/schemas/itemReference' - description: 'Parent information, if the item has a parent. Read-write.' - webUrl: - type: string - description: URL that displays the resource in the browser. Read-only. - readOnly: true - # drive - driveType: - type: string - description: Describes the type of drive represented by this resource. Values are "personal" for users home spaces, "project", "virtual" or "share". Read-only. - readOnly: true - driveAlias: - type: string - description: "The drive alias can be used in clients to make the urls user friendly. Example: 'personal/einstein'. This will be used to resolve to the correct driveID." - owner: - $ref: '#/components/schemas/identitySet' - quota: - $ref: '#/components/schemas/quota' - items: - type: array - items: - $ref: '#/components/schemas/driveItem' - description: All items contained in the drive. Read-only. Nullable. - readOnly: true - root: - $ref: '#/components/schemas/driveItem' - description: Drive item describing the drive's root. Read-only. - special: - type: array - items: - $ref: '#/components/schemas/driveItem' - description: A collection of special drive resources. - '@libre.graph.hasTrashedItems': - type: boolean - description: Indicates whether the drive has items in the trash. Read-only. - readOnly: true - driveRecipient: - type: object - description: | - Represents a person, group, or other recipient to share a drive item with using the invite action. - - When using invite to add permissions, the `driveRecipient` object would specify the `email`, `alias`, - or `objectId` of the recipient. Only one of these values is required; multiple values are not accepted. - properties: - #alias: - # type: string - # description: The alias of the domain object, for cases where an email address is unavailable (e.g. groups). - #email: - # type: string - # description: The email address for the recipient, if the recipient has an associated email address. - objectId: - type: string - description: The unique identifier for the recipient in the directory. - "@libre.graph.recipient.type": - type: string - description: When the recipient is referenced by objectId this annotation is used to differentiate `user` and `group` recipients. - default: user - identitySet: - type: object - description: Optional. User account. - properties: - application: - $ref: '#/components/schemas/identity' - description: Optional. The application associated with this action. - device: - $ref: '#/components/schemas/identity' - description: Optional. The device associated with this action. - user: - $ref: '#/components/schemas/identity' - description: Optional. The user associated with this action. - # this is not part of the ms graph api. there, only the sharepointIdentitySet used in grantedToV2 has a group - group: - $ref: '#/components/schemas/identity' - description: Optional. The group associated with this action. - sharePointIdentitySet: - type: object - description: This resource is used to represent a set of identities associated with various events for an item, such as created by or last modified by. - properties: - user: - $ref: '#/components/schemas/identity' - description: Optional. The user associated with this action. - group: - $ref: '#/components/schemas/identity' - description: Optional. The group associated with this action. - - # unused - #application: - # $ref: '#/components/schemas/identity' - # description: Optional. The application associated with this action. - - # unused - #device: - # $ref: '#/components/schemas/identity' - # description: Optional. The device associated with this action. - # other properties omitted for now - identity: - type: object - required: - - displayName - properties: - displayName: - type: string - description: 'The identity''s display name. Note that this may not always be available or up to date. For example, if a user changes their display name, the API may show the new value in a future response, but the items associated with the user won''t show up as having changed when using delta.' - id: - type: string - description: Unique identifier for the identity. - '@libre.graph.userType': - type: string - description: 'The type of the identity. This can be either "Member" for regular user, "Guest" for guest users or "Federated" for users imported from a federated instance. Can be used by clients to indicate the type of user. For more details, clients should look up and cache the user at the /users endpoint.' - invitation: - type: object - description: | - Represents an invitation to a drive item. - properties: - invitedUserDisplayName: - type: string - description: The display name of the user being invited. - invitedUserEmailAddress: - type: string - description: The email address of the user being invited. Required. - invitedUserMessageInfo: - $ref: '#/components/schemas/invitedUserMessageInfo' - description: Additional information about the invitation message. - sendInvitationMessage: - type: boolean - description: Indicates whether an invitation message should be sent to the user. - inviteRedirectUrl: - type: string - description: The URL to which the user is redirected after accepting the invitation. Required. - inviteRedeemUrl: - type: string - description: The URL that the user can use to redeem the invitation. Read-only. - readOnly: true - status: - type: string - description: The status of the invitation. Read-only. - readOnly: true - invitedUser: - $ref: '#/components/schemas/user' - description: The user object of the invited user. Read-only. - readOnly: true - invitedUserType: - type: string - description: The type of user being invited. - invitedUserMessageInfo: - type: object - description: Additional information about the invitation message. - properties: - ccRecipients: - type: array - items: - $ref: '#/components/schemas/recipient' - description: Additional recipients who will receive a copy of the invitation message. - customizedMessageBody: - type: string - description: The customized message body that will be included in the invitation message. - messageLanguage: - type: string - description: The language of the invitation message. - recipient: - type: object - description: Represents a recipient of an invitation. - properties: - emailAddress: - $ref: '#/components/schemas/emailAddress' - description: The email address of the recipient. - emailAddress: - type: object - description: Represents an email address. - properties: - address: - type: string - description: The email address. - name: - type: string - description: The name associated with the email address. - - objectIdentity: - description: Represents an identity used to sign in to a user account - type: object - properties: - issuer: - description: domain of the Provider issuing the identity - type: string - issuerAssignedId: - description: The unique id assigned by the issuer to the account - type: string - passwordProfile: - description: Password Profile associated with a user - type: object - properties: - forceChangePasswordNextSignIn: - type: boolean - description: If true the user is required to change their password upon the next login - default: false - password: - type: string - writeOnly: true - description: The user's password - sharingLink: - description: | - The `SharingLink` resource groups link-related data items into a single structure. - - If a `permission` resource has a non-null `sharingLink` facet, the permission represents a sharing link (as opposed to permissions granted to a person or group). - type: object - properties: - type: - $ref: '#/components/schemas/sharingLinkType' - preventsDownload: - type: boolean - description: If `true` then the user can only use this link to view the item on the web, and cannot use it to download the contents of the item. - readOnly: true - webUrl: - type: string - description: A URL that opens the item in the browser on the website. - readOnly: true - '@libre.graph.displayName': - type: string - description: Provides a user-visible display name of the link. Optional. Libregraph only. - '@libre.graph.quickLink': - type: boolean - description: The quicklink property can be assigned to only one link per resource. A quicklink can be used in the clients to provide a one-click copy to clipboard action. Optional. Libregraph only. - # unused - #webHtml: - # type: string - # description: For `embed` links, this property contains the HTML code for an `