Skip to main content
Skip table of contents

REST-API

This page describes the REST-API of edu-sharing

on this page:

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

Existing clients / Implementations


Clients can be created using the openapi spec at <your-domain>/edu-sharing/rest/openapi.json

Angular:

https://www.npmjs.com/package/ngx-edu-sharing-api

Java / Maven:
CODE 
         <dependency>
            <groupId>org.edu_sharing</groupId>
            <artifactId>edu_sharing-community-repository-backend-services-rest-client-java</artifactId>
            <version>8.0.0</version>
        </dependency>

[...]

 	<repositories>
        <repository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>central</id>
            <name>Maven Repository Switchboard</name>
            <url>https://repo1.maven.org/maven2</url>
        </repository>
        <repository>
            <id>edusharing-remote</id>
            <url>https://artifacts.edu-sharing.com/repository/maven-remote/</url>
            <releases>
                <enabled>true</enabled>
                <updatePolicy>always</updatePolicy>
            </releases>
            <snapshots>
                <enabled>true</enabled>
                <updatePolicy>always</updatePolicy>
            </snapshots>
        </repository>
    </repositories>


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 started.
You simply send the Basic Auth using the Base64 encoding for "username:password"

CODE 
Authorization: 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>

AppAuth / Auth via Signature

When your app is registered in the repository, you may authenticate as any user without credentials by providing your app signature


First of all, register your application (Admin Tools → Remote Systems → Upload XML)
Make sure that your app provides at least the following data:

CODE 
<id>your-app-id</id>
<public_key>your apps public key</public_key>
<domain>localhost</domain> <!-- the domain from which this app will make requests, otherwise authentication will be rejected -->
<host>127.0.0.1</host> <!-- the host from which this app will make requests, otherwise authentication will be rejected -->
<trustedclient>true</trustedclient> <!-- must be true -->

Then, authenticate at the endpoint

CODE 
POST edu-sharing/rest/authentication/v1/appauth/{userId}

Set the appropriate username in the url, and (optional) send the following payload for userprofile:

CODE 
{
  "primaryAffiliation": "string",
  "extendedAttributes": {"attname":["attval_1","attval_2"]},
  "firstName": "string",
  "lastName": "string",
  "email": "string"
}

In order to authenticate with your app, please attach the following headers to your request:

X-Edu-App-Id: your-app-id
X-Edu-App-Sig: <signature>
X-Edu-App-Signed: A Signed Payload which must include your timestamp and should include other dynamic data
X-Edu-App-Ts: timestamp (Unix Timestamp in Milliseconds, like System.currentTimeMillis())

When everything works, you will get a response including the actual authorityName (this is may or may not the username you provided, depending on several internal constrains) as well as a ticket. Use the ticket for the Edu-Ticket-Auth (see above)

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

  1. 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"
        }
    }
}

  2. 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"
        }
    }
}

    AppAuth/Signature Auth:

  3. LoginApiTestAppAuth.java LoginApiTestAppAuth.properties.xml
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close