REST-API

Connecting & URL

The edu-sharing REST API is located at:

CODE

<your-domain>/edu-sharing/rest

Swagger

In order to discover and test the endpoints, edu-sharing ships with a swagger REST documentation GUI.

You can access it via:

CODE

<your-domain>/edu-sharing/swagger

Basic Requests

In order to communicate with the API, the "Accept" and "Content-Type" header NEEDS to be set:

CODE

Accept: application/json
Content-Type: application/json

Note: For some endpoints that accept form data, the Content-Type should be 'multipart/form-data' instead

Authentication

The API supports different Authentication methods as described below.

If you do not provide any authentication, the system will use the guest user (if existing) or deny all data requests if no guest is configured.

In order to check if the authentication succeeded, please send these requests to the following endpoint:

CODE

<your-domain>/edu-sharing/rest/authentication/v1/validateSession

Basic Auth

This is recommended to get startet.
You simply send the Basic Auth using the Base64 encoding for "username:password"

CODE

Authentication: Basic dGVzdDp0ZXN0// authenticate as user test with password test

Session Auth

As soon as the system provides you with a Session (found in the "Set-Cookie" Response Header, "JSESSIONID"), it is possible to reuse this session to keep your authentication state:

CODE

Cookie: JSESSIONID=<sessionid>

OAuth

You can also use an accessToken previously generated via OAuth to authenticate.

CODE

Authentication: Bearer <accessToken>

Edu Ticket Auth

If you have an Edu Ticket (this is usually provided via AuthByApp), you can also use the ticket to authenticate.

CODE

Authentication: EDU-TICKET <ticketid>

Examples

The following examples show basic tasks like creating nodes (files/folders) or searching data.

In this example, the authentication is skipped. Please make sure to provide an appropriate authentication as described above.

Creating an object in the user home folder

Create the node (which will be an empty object containing just the name and metadata)
Request:

CODE

POST /edu-sharing/rest/node/v1/nodes/-home-/-userhome-/children?type=ccm:io& renameIfExists=true HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Accept: application/json
User-Agent: PostmanRuntime/7.19.0
Cache-Control: no-cache
Postman-Token: 1e35070e-2de9-4584-8ff5-8fbcb83afde1,86784f35-ef92-476c-804c-d5ade3e484b1
Host: localhost:8080
Accept-Encoding: gzip, deflate
Content-Length: 26
Cookie: JSESSIONID=BA0981CD4FC20445593000EA669AF4CE
Connection: keep-alive
cache-control: no-cache

{
"cm:name":["Test.txt"]
}

Response:

CODE

{
    "node": {
        "isDirectory": false,
        "commentCount": 0,
        "ref": {
            "repo": "local",
            "id": "b2f2f730-f852-4e52-90ab-3c6846b6a67d",
            "archived": false,
            "isHomeRepo": true
        },
        "parent": {
            "repo": "local",
            "id": "79705b2a-630a-4cb0-b983-fd0c40c2b6f8",
            "archived": false,
            "isHomeRepo": true
        },
        "type": "ccm:io",
        "aspects": [
            "cclom:lifecycle",
            "ccm:eduscope",
            "cclom:technical",
            "ccm:iometadata",
            "ccm:usageaspect",
            "sys:referenceable",
            "sys:localized",
            "cclom:schema",
            "cm:metadataset",
            "ccm:licenses",
            "ccm:commonlicenses",
            "cclom:rights",
            "cm:thumbnailed",
            "cm:auditable",
            "ccm:lomreplication",
            "cclom:meta-metadata",
            "cclom:general",
            "ccm:educontext"
        ],
        "name": "Test.txt",
        "title": null,
        "metadataset": "default",
        "description": null,
        "repositoryType": "ALFRESCO",
        "createdAt": "2019-11-12T10:06:46Z",
        "createdBy": {
            "profile": null,
            "firstName": "Administrator",
            "lastName": "",
            "mailbox": "admin@alfresco.com"
        },
        "modifiedAt": "2019-11-12T10:06:46Z",
        "modifiedBy": {
            "profile": null,
            "firstName": "Administrator",
            "lastName": "",
            "mailbox": "admin@alfresco.com"
        },
        "access": [
            "ReadAll",
            "Comment",
            "AddChildren",
            "ChangePermissions",
            "Write",
            "Delete",
            "CCPublish"
        ],
        "contentVersion": null,
        "contentUrl": "http://localhost:8080/edu-sharing/eduservlet/redirect?APP_ID=local&NODE_ID=b2f2f730-f852-4e52-90ab-3c6846b6a67d",
        "downloadUrl": null,
        "properties": {},
        "mimetype": "text/plain",
        "mediatype": "file-txt",
        "size": null,
        "preview": {
            "isIcon": false,
            "isGenerated": true,
            "url": "http://localhost:8080/edu-sharing/preview?nodeId=b2f2f730-f852-4e52-90ab-3c6846b6a67d&storeProtocol=workspace&storeId=SpacesStore&dontcache=1573553206760",
            "width": null,
            "height": null
        },
        "iconURL": "http://localhost:8080/edu-sharing/themes/default/images/common/mime-types/svg/file-txt.svg",
        "licenseURL": "http://localhost:8080/edu-sharing/ccimages/licenses/none.svg",
        "collection": null,
        "owner": {
            "profile": null,
            "firstName": "Administrator",
            "lastName": "",
            "mailbox": "admin@alfresco.com"
        }
    }
}

Take the node → ref → id to address the node in the next request
Request:

CODE

POST /edu-sharing/rest/node/v1/nodes/-home-/b2f2f730-f852-4e52-90ab-3c6846b6a67d/content?mimetype=text/plain HTTP/1.1
Host: localhost:8080
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: application/json
User-Agent: PostmanRuntime/7.19.0
Cache-Control: no-cache
Postman-Token: 65f93cbe-bfb1-415c-ab2d-2376b74dfdbb,017cc9bd-6eb6-4669-871b-fd877e6f55b5
Host: localhost:8080
Accept-Encoding: gzip, deflate
Cookie: JSESSIONID=BA0981CD4FC20445593000EA669AF4CE
Content-Length: 210
Connection: keep-alive
cache-control: no-cache


Content-Disposition: form-data; name="file"; filename="/C:/Test.txt


------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response:

CODE

{
    "node": {
        "isDirectory": false,
        "commentCount": 0,
        "ref": {
            "repo": "local",
            "id": "b2f2f730-f852-4e52-90ab-3c6846b6a67d",
            "archived": false,
            "isHomeRepo": true
        },
        "parent": {
            "repo": "local",
            "id": "79705b2a-630a-4cb0-b983-fd0c40c2b6f8",
            "archived": false,
            "isHomeRepo": true
        },
        "type": "ccm:io",
        "aspects": [
            "cclom:lifecycle",
            "ccm:eduscope",
            "cclom:technical",
            "ccm:iometadata",
            "ccm:usageaspect",
            "sys:referenceable",
            "sys:localized",
            "cclom:schema",
            "cm:metadataset",
            "ccm:licenses",
            "ccm:commonlicenses",
            "cclom:rights",
            "cm:thumbnailed",
            "cm:titled",
            "cm:auditable",
            "ccm:lomreplication",
            "cclom:meta-metadata",
            "cclom:general",
            "cm:author",
            "ccm:educontext"
        ],
        "name": "Test.txt",
        "title": null,
        "metadataset": "default",
        "description": null,
        "repositoryType": "ALFRESCO",
        "createdAt": "2019-11-12T10:06:46Z",
        "createdBy": {
            "profile": null,
            "firstName": "Administrator",
            "lastName": "",
            "mailbox": "admin@alfresco.com"
        },
        "modifiedAt": "2019-11-12T10:26:45Z",
        "modifiedBy": {
            "profile": null,
            "firstName": "Administrator",
            "lastName": "",
            "mailbox": "admin@alfresco.com"
        },
        "access": [
            "ReadAll",
            "Comment",
            "AddChildren",
            "ChangePermissions",
            "Write",
            "Delete",
            "CCPublish"
        ],
        "contentVersion": null,
        "contentUrl": "http://localhost:8080/edu-sharing/eduservlet/redirect?APP_ID=local&NODE_ID=b2f2f730-f852-4e52-90ab-3c6846b6a67d",
        "downloadUrl": "http://localhost:8080/edu-sharing/eduservlet/redirect?APP_ID=local&NODE_ID=b2f2f730-f852-4e52-90ab-3c6846b6a67d¶ms=display%3Ddownload",
        "properties": {},
        "mimetype": "text/plain",
        "mediatype": "file-txt",
        "size": "4",
        "preview": {
            "isIcon": false,
            "isGenerated": true,
            "url": "http://localhost:8080/edu-sharing/preview?nodeId=b2f2f730-f852-4e52-90ab-3c6846b6a67d&storeProtocol=workspace&storeId=SpacesStore&dontcache=1573554406026",
            "width": null,
            "height": null
        },
        "iconURL": "http://localhost:8080/edu-sharing/themes/default/images/common/mime-types/svg/file-txt.svg",
        "licenseURL": "http://localhost:8080/edu-sharing/ccimages/licenses/none.svg",
        "collection": null,
        "owner": {
            "profile": null,
            "firstName": "Administrator",
            "lastName": "",
            "mailbox": "admin@alfresco.com"
        }
    }
}