Equella 6.1 Rest API Guide

EQUELLA
REST API Guide

Version 6.1
Document History
Document
No.
1
Reviewed
15/05/2013
Finalised
15/05/2013
Published
15/05/2013
May 2013 edition.
Information in this document may change without notice. EQUELLA and its
accompanying documentation are furnished under a non-disclosure, evaluation
agreement or licence agreement. Copying, storing, transmitting, or otherwise reproducing
the software or this document in any form without written permission from Pearson is
strictly forbidden.
All products, other than EQUELLA, named in this document are the property of their
respective owners.
Property of:
Pearson
Level 1, 11 Elizabeth Street
Hobart, Australia, 7000
Copyright 2013 Pearson
Contact documentation@equella.com for matters relating to documentation.
EQUELLA 6.1 REST API Guide
2|Page
Table of Contents
EQUELLA REST API .......................................................................................................... 5
OAuth Login ................................................................................................................... 6
OAuth Client Configuration ............................................................................................ 6
Accessing OAuth settings ............................................................................................ 6
Registering OAuth client applications ............................................................................ 7
Generated tokens .................................................................................................... 10
Obtaining An OAuth Token ........................................................................................... 10
Obtaining a token via Authorization Code Grant ........................................................... 10
Obtaining a token via Implicit Grant ........................................................................... 11
Obtaining a token via Client Credentials Grant ............................................................. 12
Searching for Resources ................................................................................................. 13
Searching personal resources ....................................................................................... 14
Examples .................................................................................................................. 15
Obtaining a Resource ..................................................................................................... 16
Requesting specific details ........................................................................................... 16
Comments .............................................................................................................. 16
History ................................................................................................................... 16
Example resource ....................................................................................................... 17
Contributing a New Resource .......................................................................................... 18
Files.......................................................................................................................... 18
Uploading Files ........................................................................................................ 18
Directories ................................................................................................................. 19
Files on the dir endpoint ........................................................................................... 19
Navigation ................................................................................................................. 19
New Versions of a Resource ............................................................................................ 21
Files.......................................................................................................................... 21
Examples .................................................................................................................. 21
Editing an Existing Resource ........................................................................................... 22
Locking ..................................................................................................................... 22
Locking example ...................................................................................................... 23
Files.......................................................................................................................... 23
Extended actions ........................................................................................................ 23
Notifications ................................................................................................................. 24
Retrieving notifications ................................................................................................ 24
Clearing notifications .................................................................................................. 24
Tasks ........................................................................................................................... 25
3|Page
Retrieving tasks ......................................................................................................... 25

External system uses ..................................................................................................... 26
Retrieve a list of connectors ......................................................................................... 26
Find uses for a resource .............................................................................................. 26
Users and Groups .......................................................................................................... 27
Reassign the ID of existing users .................................................................................. 27
Re-assign the ID of existing groups .............................................................................. 27
Formats ....................................................................................................................... 28
Examples .................................................................................................................. 36
Internal REST API Reference ........................................................................................ 42
Contact Client Support ................................................................................................ 46
4|Page
EQUELLA REST API

This guide describes the concepts and some low level specifics of the EQUELLA REST API.
For a detailed EQUELLA REST API reference you should refer to the inbuilt API
documentation at .../apidocs.do
In this document your institution URL will be referred to as the text ... , so if your
institution base URL is http://my.inst.edu/ then you will find the inbuilt documentation at
http://my.inst.edu/apidocs.do
In this document all placeholder variables are shown in square brackets and should not
be treated literally. For example,
GET .../api/item/[uuid]/[version]
would refer to:

GET http://my.inst.edu/api/item/5950e6b8-6ce4-11e1-b335-fb4e4824019b/2
where 5950e6b8-6ce4-11e1-b335-fb4e4824019b is a UUID of a resource and 2 is the

version of the resource
All representations returned by the REST API are in JSON format (http://www.json.org/),
no other formats are supported.
5|Page
OAuth Login
The EQUELLA REST API supports OAuth 2.0 login. To use OAuth login, you must first
register an OAuth Client within EQUELLA. This can be done from the OAuth Settings
function accessed from the Settings page. (See the Registering OAuth client applications
section on page 7.
NOTE: You will need the following privileges to fully administer OAuth Clients:
CREATE_OAUTH_CLIENT
EDIT_OAUTH_CLIENT
DELETE_OAUTH_CLIENT
ADMINISTER_OAUTH_TOKENS.
The configuration of your client depends on which OAuth flow you intend to use.
EQUELLA supports three OAuth flows:
1. Authorization Code Grant ( http://tools.ietf.org/html/rfc6749#section-4.1 )
2. Implicit Grant ( http://tools.ietf.org/html/rfc6749#section-4.2 )
3. Client Credentials Grant ( http://tools.ietf.org/html/rfc6749#section-4.4 )
OAuth Client Configuration

All registered OAuth Clients need a Name (for use within EQUELLA only), Client ID and,
a Client Secret. Further configuration options depend upon the flow you wish to use.
See Registering OAuth client applications on page 7 for further information.
Accessing OAuth settings

OAuth clients are configured via the OAuth settings function accessed from the
Settings page. The OAuth settings page also lists Generated tokens.
To access the OAuth settings page

1. Select Settings from the navigation menu, then OAuth settings. The OAuth settings
page displays, as shown in Figure 1.
6|Page
Figure 1 OAuth settings page
Registering OAuth client applications

The Registered client applications section of the OAuth settings page displays any
existing registered OAuth clients, and allows new clients to be added.
To register a new Oauth client

1. Click the Register new client application link. The Create new OAuth client page
displays, as shown in Figure 2.
Figure 2 Create new OAuth client page
7|Page
2. Enter a Descriptive name (only used internally). The Client ID and Client secret
are automatically generated, but the Client ID may be replaced with a user-defined
value.
3. Select an OAuth flow from the drop-down list, depending on the type of OAuth client
being registered. See the following options:
To Configure an OAuth Client for Authorisation Code Grant

To use this OAuth flow, your client application needs to be a web application with a URL
that can be redirected to.
1. From the OAuth flow drop-down, select 'Authorisation code grant and implicit
grant'. The Create new OAuth client page displays some extra options. An example is
shown in Figure 3.
Figure 3 Authorisation code grant options

2. Select 'I want to use a custom redirect URL' (this MUST be selected) enter the
Redirect URL of the endpoint in your application that will handle the OAuth redirects
and responses from EQUELLA, e.g. http://mywebapp.com/oauthlogin
3. Click
To configure an OAuth Client for Implicit Grant

Use this flow if your client is Javascript in a web browser that needs to make secure API
calls, or your client application supports an embeddable browser (such as a C# Winforms
application) where you can extract the location URL.
1. From the OAuth flow drop-down, select 'Authorisation code grant and implicit
grant'. The Create new OAuth client page displays some extra options. An example is
shown in Figure 4.
8|Page
Figure 4 Implicit grant options

2. Select 'My application doesn't host a redirect URL, I want to use the default'
for the Redirect URL if using an embedded browser, otherwise select 'I want to use
a custom redirect URL' and enter the URL of the page where your Javascript is
loaded.
3. Click
To configure an OAuth Client for Client Credentials Grant

Use this flow if your client application is not web based in any way, e.g. it is a Python
script. When using this flow your client must act as a pre-configured user.
1. From the OAuth flow drop-down, select 'Client credentials grant and LTI
authentication'. The Create new OAuth client page displays some extra options. An
example is shown in Figure 5.
9|Page
Figure 5 Client credentials grant and LTI authentication

2. Click
to open the Select User(s) dialog and search for and select the
required user. NOTE: A user MUST be selected.
When the client application makes API calls it will do so as this user (since a user is
never asked to login)
3. Click
Generated tokens
The Generated tokens section of the OAuth settings page lists all tokens that have been
generated for all registered client applications. Client applications will create tokens using
the methods outlined in Obtaining An OAuth Token. To view or remove tokens the
ADMINISTER_OAUTH_TOKENS privilege is required.
Obtaining An OAuth Token

Your client application must obtain an OAuth token to make secure API calls. Once you
have retrieved the token, each API call needs to include an "X-Authorization" HTTP
header with a value of "access_token=[token]"
Obtaining a token via Authorization Code Grant

This is a multi step process: first you must obtain an authorisation code using a redirect
response or a browser window.location redirect, then the user logs into EQUELLA, a
code is returned to your application via a redirect, your application obtains a token using
that code.
10 | P a g e
1. Your application must redirect to the OAuth authorisation endpoint

.../oauth/authorise:
.../oauth/authorise?response_type=code&client_id=[client
id]&redirect_uri=[redirect URL]
which could be acheived by:

a. 302 redirect
b. Javascript to redirect the browser
NOTE: If you prefer, the authorisation endpoint can also be accessed at
.../oauth/authorize (z instead of s)
2. User is presented with an EQUELLA login screen (if they are not already logged in,
e.g. in another browser tab)
3. The EQUELLA OAuth authorisation endpoint redirects to your application (as
determined by the redirect_uri) with a code parameter appended:
[redirect URL]?code=[a short lived code]
Do not store this code, it has a limited lifespan (2 minutes) and can only be used
once, even if the request containing the code fails. In this case you would need to
obtain another code.
4. Your application needs to detect the presence of the code parameter and do a server
side request to the EQUELLA OAuth token endpoint:
.../oauth/access_token?grant_type=authorization_code&client_id=[client
id]&code=[code from step 3]
where a token will returned in JSON format. For example,

{
"scope" : null,
"state" : null,
"access_token" : "1d031eef-185a-4c22-a922-b996391b9f4f",
"refresh_token" : null,
"token_type" : "equella_api",
"expires_in" : 9223372036854775807
}
Your application must extract the access_token value.
Obtaining a token via Implicit Grant

To obtain a token using this flow, simply redirect to the EQUELLA OAuth authorisation
endpoint with response_type=token
1. Set the browser location to:
.../oauth/authorise?response_type=token&client_id=[client
id]&redirect_uri=["default" for embedded browser, or redirect URL for Javascript]
2. User is presented with an EQUELLA login screen (if they are not already logged in,
e.g. in another browser tab)
11 | P a g e
3. The EQUELLA OAuth authorisation endpoint redirects to either the inbuilt redirect URL
(if "default" was specified) or the supplied redirect_uri with the token appended to the
URL as a URL fragment:
[redirect URL]#access_token=[token]
Your application must extract the token from the browser URL.
Obtaining a token via Client Credentials Grant

This is the most straightforward OAuth flow, but requires that client act as a single, preconfigured, user.
By requesting:
.../oauth/access_token?grant_type=client_credentials&client_id=[client
id]&client_secret=[client secret]&redirect_uri=default
a token will returned in JSON format. . E.g.

{
"scope" : null,
"state" : null,
"access_token" : "1d031eef-185a-4c22-a922-b996391b9f4f",
"refresh_token" : null,
"token_type" : "equella_api",
"expires_in" : 9223372036854775807
}
Your application must extract the access_token value.
12 | P a g e
Searching for Resources

To search for resources you perform a GET request on the .../api/search endpoint.
Several parameters are supported, all of them are optional:
start - The first record of the search results to return (zero based, i.e. first result is
the zeroth result). Default value is 0.
length - The number of results to return. Default value is 10. Maximum value is
100.
q - The search query. Default value is blank.
collections - A comma separated list of collection UUIDs. Default behaviour is to

search all collections.
order - The order of the search results. Allowed values are 'relevance', 'modified',
'name' or 'rating'. Default value is 'modified' if the query parameter is blank, or
'relevance' if a query is supplied.
reverse - Reverse the order of the search results. Allowed values are 'true' or 'false'.
Default is 'false'.
where - You can use a where clause to perform advanced searching over resource
metadata.
The where clause is designed to be a SQL-like query language. The specification of the
where clause (in BackusNaur Form
http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form ) is:
WHERE STATEMENT
BOOLEAN_EXPR
OR_BOOLEAN_EXPR
AND_BOOLEAN_EXPR
CLAUSE
BRACKETS
COMPARISON
EXISTS_CLAUSE
XPATH
COMPARISON_OP
::=
::=
::=
::=
::=
::=
::=
::=
::=
::=
"where"? BOOLEAN_EXPR
OR_BOOLEAN_EXPR
AND_BOOLEAN_EXPR ("or" AND_BOOLEAN_EXPR)*
CLAUSE ("and" CLAUSE)*
"not" CLAUSE | BRACKETS | COMPARISON | EXISTS_CLAUSE
"(" BOOLEAN_EXPR ")"
XPATH COMPARISON_OP COMPARISON_RHS
XPATH "exists"
"/" (ALPHA | NUMBER | [/._:@])+
"=" | "is" | "<>" | "is not" | "<" | "<=" | ">" | ">="
COMPARISON_RHS
STRING_VALUE
NUMBER_VALUE
GROUP_VALUE
STRING
ALPHA
NUMBER
::=
::=
::=
::=
::=
::=
::=
"like" | "not like" | "in" | "not in"

"null" | NUMBER_VALUE | STRING_VALUE | GROUP_VALUE
"'" STRING "'"
NUMBER+
"(" STRING_VALUE ("," STRING_VALUE)* ")"
(ALPHA | [0-9] | ...)*
[a-zA-Z]
[0-9]
An example where clause is "where /xml/item/category not like 'dog%'" (quotes not
included). Note that all query string parameters need to be URL encoded, so to use this
example where clause:
GET .../api/search?where=where%20%2Fxml%2Fitem%2Fcategory%20not%20like%20'dog%25'
13 | P a g e
Any schema node you search on in the where clause must have "Index for Power
Searches" selected in the schema editor of the Administration Console.
showall - If 'true' then include resources that are not live. Allowed values are 'true'
or 'false'. Default is 'false'.
info - How much information to return for each result. Allowed values are 'basic',
'metadata', 'detail', 'attachment', 'navigation', 'drm' and 'all'. Multiple values can be
specified via comma separation. Specifying an info parameter with no value will
return resource representations containing only uuid, version and links fields only.
'basic' returns resource names and descriptions.
'metadata' will return the resource metadata xml.
'detail' will return miscellaneous data on each resource such as the resource owner
and date of last modification.
'attachment' will return the list of attachments on each resource.
'navigation' will return the navigation tree of the resource (if any).
'drm' will return the digital rights management settings on the resource (if any).
'all' returns all of the above, limited by the user's privileges.
You should specify the minimum information that you need. Use of 'all' is not
recommended as large amounts of data are returned and many database queries are
required to be executed by the server.
The format of the results returned by this endpoint is the Search Results Representation.
Searching personal resources

There are a number of pre-configured search types available for searching the current
user's own content. The available search types are listed under the
.../api/search/myresources endpoint.
Retrieving available search types

Perform a GET on the .../api/search/myresources. This endpoint returns an array of
Search Definition Representations.
Performing a personal resources search

Perform a GET on the .../api/search/myresources/[id] endpoint, where [id] is the ID of a
search definition returned from the .../api/search/myresources endpoint.
Several parameters are supported, all of them are optional. See Searching for Resources
for the allowed parameters, as they are identical.
The format of the results returned by this endpoint is the Search Results Representation.
14 | P a g e
Examples
Search for first 10 results, with query 'the veronicas' and order by rating
GET .../api/search?q=the%20veronicas&order=rating
Search for results 11 to 20, with query 'cats' within two specified collections, showing
resources that are not live, ordered by date last modified (most recent first).
GET .../api/search?start=10&length=10&q=cats&collections=75479a16-cdd4-4aa7-86579412d3aec1e1,35d5d0d5-422b-24b2-82b2-0ee6bb8022ab&showall=true&order=modified
Using the 'where' parameter (/xml/item/pagecount in (1,2,3,4)), returning

additional information for each resource.
GET
.../api/search?where=%2Fxml%2Fitem%2Fpagecount%20in%20(1%2C2%2C3%2C4)&info=detail
,attachment
15 | P a g e
Obtaining a Resource
To view details of a particular resource you will need to know its UUID and version:
GET .../api/item/[uuid]/[version]
Alternatively you can list all versions of a resource by omitting the version from the path:
GET .../api/item/[uuid]
To retrieve the latest 'live' version of a resource there is a special 'latestlive' version:
GET .../api/item/[uuid]/latestlive
To retrieve the latest version of a resource, regardless of status, there is a special 'latest'
version:
GET .../api/item/[uuid]/latest
Attempting to perform a GET on .../api/item without a UUID will result in an error.
Requesting specific details

By default, all information is returned when retrieving resource details (unlike the search
endpoint), although you may opt for less information via an 'info' query string parameter.
You would do this for performance reasons; the less information queried and sent back
over the network the faster your API calls will be.
An example:
GET .../api/item/[uuid]/[version]?info=basic,detail
Valid values are the same as the search 'info' parameter (See Searching For Resources).
NOTE: Some information may not be show depending on the privileges of the user, e.g.
attachments will not be shown if the user making the API request does not have the
VIEW_ITEM privilege. Having only DISCOVER_ITEM allows the user to see minimal
information.
Comments and history on a resource can only be retrieved via sub-entity URLs.
Comments
To list all comments on a resource:
GET .../api/item/[uuid]/[version]/comment
Currently the comments are read-only and comments cannot be edited or deleted, and no
new comments can be added. The API will be expanded in the future to allow for this.
History
To view the history of a resource (e.g. edits, submissions to moderators, status changes,
etc)
GET .../api/item/[uuid]/[version]/history
16 | P a g e
The resource history is read-only.
Example resource
An example resource, with every possible attachment type, can be seen under the
Formats - Examples section.
17 | P a g e
Contributing a New Resource

Contribution is performed by posting a JSON representation of a new resource to the item
API endpoint .../api/item
POST .../api/item
The minimum requirement is that your JSON representation contains a collection field.
Failure to specify a collection in the POSTed JSON is an error. All other fields such as
metadata are optional (but highly useful).
The new resource data will be checked for validity and the system will ensure that the
UUID/version combination does not already exist. If no UUID and version are supplied in
the representation then one will be allocated. The endpoint for the new resource will be
returned in a Location header in the POST response.
There is an optional 'draft' parameter when posting to the item URL. Setting draft=true
will keep the resource in a draft state, if this parameter is omitted, or set to false, the
resource will enter the 'live' state or be submitted for moderation (whichever applies).
E.g.
POST .../api/item?draft=true
When contributing a resource (or editing an existing resource) you can specify an optional
'waitforindex' parameter. Setting it to true will wait for the resource to be indexed for
searching before responding. This ensures that the resource is searchable by the time
you receive a response. The default value is false so that the API call can respond as
quickly as possible.
Files
To attach files to a resource you will need to obtain a temporary file area by POSTing to
the file endpoint:
POST .../api/file
which will return a JSON representation of the root folder (See File Area Representation).
You will need to extract and store the uuid field so that you can supply it when you save
the resource:
POST .../api/item?file=[file area uuid]
Uploading Files
Files can then be uploaded by PUTting the binary file to a .../api/file/[file area
uuid]/content/[filepath] URL. You can specify the parent directories of the file (if any) in
the URL. E.g.
PUT .../api/file/[file area
uuid]/content/a%20folder/another%20folder/myimage.jpeg
The directory structure will be created as required.
18 | P a g e
Attaching Files
Uploading a file will not make it appear on the resource summary page. To do so you
must create and append an Attachment Representation of type 'file' to the Resource
Representation's 'attachments' field. (See Formats on page 28)
{
"attachments": [
{
"type" : "file",
"description" : "An image",
"filename" : "a folder/another folder/myimage.jpeg"
}]
}
The filename of the attachment must be relative to the root of the file area.
GET, PUT and DELETE are supported for the .../api/file/[file area uuid]/content endpoint.
Directories
You can manipulate directories in the file area using the .../api/file/[file area uuid]/dir
endpoint. GET, PUT and DELETE are supported for this endpoint.
When using GET you can specify a deep=true parameter to get a nested representation
of the folder structure. E.g.
GET .../api/file/[file area uuid]/dir/a%20folder?deep=true
Files on the dir endpoint

You can also get information on files using GET.
E.g.
GET .../api/file/[file area uuid]/dir/a%20folder/another%20folder/myimage.jpeg
which will return a JSON representation of the file.

Attempting to delete files via the dir endpoint will result in a 400 error: only directories
can be deleted via this endpoint (use the content endpoint to delete files).
Navigation
You can edit the navigation tree of the resource by manipulating the JSON of the
resource's 'navigation' field.
Note that any new attachments you have added to the resource's 'attachment' field will
not have a UUID assigned, yet the Navigation Tab Representation has a $ref field which
relies on an existing attachment UUID. You can resolve this issue by assigning your
attachment with a UUID of "uuid:[temporary ID]" and set the navigation tab to refer to
"uuid:[temporary ID]". When the resource is saved the attachment will be assigned a
UUID and the navigation tab reference will be updated accordingly. This also applies for
XML nodes in the resource's metadata field, i.e. each temporary attachment UUID will be
scanned for and replaced with the attachment's assigned UUID in the XML.
19 | P a g e
For example:
{
..
"metadata" : "<xml><mynode>uuid:myfile</mynode></xml>",
..
"attachments" : [ {
"type" : "file",
"filename" : "myfile.jpg",
"uuid" : "uuid:myfile"
} ]
"navigation" : {
"showUnreferencedAttachments" : false,
"showSplitOption" : false,
"nodes" : [ {
"name" : "Node 1",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "uuid:myfile"
}
} ]
} ]
}
..
}
When assigning these UUIDs to your attachments make sure you assign a unique ID for
each attachment, otherwise an error will be returned.
20 | P a g e
New Versions of a Resource

You can contribute a new version of a resource by setting the 'uuid' property of the
resource to an existing resource UUID, and setting the 'version' property to zero (or the
next available version number). When POSTing the new versioned resource the
NEWVERSION_ITEM privilege will be checked.
New versioning a resource is much the same as contributing a new resource with the
following exception regarding files.
Files
If you simply POST the new version JSON then the files from the previous version will be
lost unless you specifically copy the files from the previous version. To do so you need to
obtain a temporary file are based on the existing resource (you will need one of the
following privileges to do so: EDIT_ITEM, NEWVERSION_ITEM, CLONE_ITEM,
REDRAFT_ITEM)
POST .../api/file/copy?uuid=[existing resource uuid]&version=[existing resource
version]
This gives you a file area representation which you will need to supply the UUID of when
saving the new versioned resource:
POST .../api/item?file=[file area uuid]
Examples
New versioning a resource, removing one of the files
1. Get an existing resource
GET /api/item/6fe79abc-eeb2-4aad-8ee2-b66ac8b519c5/1/?info=all
2. Modify the version number in the JSON (e.g. set it to zero for automatic new version)
3. Copy the files from the old version
POST /api/file/copy?uuid=6fe79abc-eeb2-4aad-8ee2-b66ac8b519c5&version=1
returns a link to the new files area (e.g. /api/file/90a30333-59e4-45aa-a1de5d21b4e4e468/dir )

4. List all the files
GET /api/file/90a30333-59e4-45aa-a1de-5d21b4e4e468/dir
5. Remove one of the files

DELETE /api/file/90a30333-59e4-45aa-a1de-5d21b4e4e468/content/image.jpg
6. Remove the associated attachment from the resource JSON

7. Submit the new version of the resource, tell it what files to use
POST /api/item?file=90a30333-59e4-45aa-a1de-5d21b4e4e468
Body: modified resource JSON
21 | P a g e
Editing an Existing Resource

To edit an existing resource you should obtain an existing resource JSON representation
(e.g. via GET), modify the required fields in the JSON and then PUT the modified JSON to
the resource's API URL. E.g.
1. Get the resource
GET .../api/item/e25586c8-6d5a-11e1-a751-a4f34824019b/1
2. Make edits to response of step 1

3. Save the updated resource
PUT .../api/item/e25586c8-6d5a-11e1-a751-a4f34824019b/1
When using PUT the status of the resource will not be changed, e.g. if it is in 'draft' status
it will stay in 'draft' status. To submit an edited resource you need to post to the 'submit'
sub-entity (See Extended actions)
Locking
You can see if a resource is locked by accessing the /lock sub-entity which will return
either a 404 error if the item is not locked, or a Lock Representation.
GET .../api/item/[uuid]/[version]/lock
You may unlock a resource by calling DELETE on the lock. Note that this means you can
delete a lock obtained by another user (i.e. it is a force unlock), so use with caution.
DELETE .../api/item/[uuid]/[version]/lock
To obtain a lock, POST to the lock URL (the resource must not already be locked)
POST .../api/item/[uuid]/[version]/lock
This will return a JSON representation of the lock. Once you obtain this lock you will
need to extract the lock 'uuid' property.
The resource is now locked, any attempt to modify the resource will now result in a lock
error occurring and a 409 response being returned unless the lock parameter is passed
with the edit. I.e.
PUT .../api/item/[uuid]/[version]?lock=[lock uuid]
This will commit the edits and then unlock the resource. You can specify a
keeplocked=true parameter to retain the lock.
Attempting to lock a resource that is already locked will result in a 409 (conflict)
response.
Attempting to unlock a resource that is not locked will result in a 404 (the lock is not
found) response.
22 | P a g e
Locking example
1. GET .../api/item/e25586c8-6d5a-11e1-a751-a4f34824019b/1
2. POST .../api/item/e25586c8-6d5a-11e1-a751-a4f34824019b/1/lock
3. Retrieve lock UUID from response of step 2
4. Make edits to response of step 1
5. PUT .../api/item/e25586c8-6d5a-11e1-a751-a4f34824019b/1?lock=[uuid]
Files
If you need to edit the files of the resource you should use the .../api/file/copy endpoint
(see New Versions Of A Resource)
If the file parameter is not supplied when POSTing the edited resource then the files will
remain unchanged.
Extended actions
There are a number of edits on a resource which can only be performed by POSTing to an
action/[action name] sub-entity. These actions are:
archive
redraft
reset
reactivate
restore
resume
submit
suspend
So to archive a resource you would:

POST .../api/item/[uuid]/[version]/action/archive
which will immediately archive the resource (permissions and current resource status
permitting)
23 | P a g e
Notifications
You can search for and clear user notifications using the .../api/notification endpoint.
Retrieving notifications
To retrieve user notifications you perform a GET request on the .../api/notification
endpoint.
length - The number of results to return. Default value is 10. Maximum value is 100.

type - Filter results by notification type. Allowed values are 'all', 'wentlive', 'rejected',
'badurl', 'watchedwentlive' and 'overdue'. Default value is 'all'
The endpoint returns a Search Results Representation, where the results array contains
Notification Representations.
Clearing notifications
To clear a notification send a DELETE request to the .../api/notification/[id] endpoint,
where [id] is the id of a notification.
24 | P a g e
Tasks
You can search for tasks using the .../api/task endpoint.
Retrieving tasks
To retrieve user tasks you perform a GET request on the .../api/task endpoint.
length - The number of results to return. Default value is 10. Maximum value is
100.

type - Filter results by notification type. Allowed values are 'all', 'wentlive', 'rejected',
'badurl', 'watchedwentlive' and 'overdue'. Default value is 'all'
Task Status Representations.
25 | P a g e
External system uses

You can view where EQUELLA content is used in external systems using the connector
endpoint.
To use the connector endpoint you need to have External system connectors configured
within EQUELLA. See the EQUELLA Push to LMS Guide for further information.
Retrieve a list of connectors

To view the list of connectors available for any resource perform a GET on
.../api/connector/[resource uuid]/[resource version]
An array of Connector Representations is returned.
Find uses for a resource

To view the uses of a resource with a particular connector perform a GET on
.../api/connector/[resource uuid]/[resource version]/use/[connector uuid]
Connector Content Representations.
26 | P a g e
Users and Groups

The current functionality is limited to very specific functions but will be expanded in the
future.
Reassign the ID of existing users

This function changes all references of a user ID to another ID assigned by you. This can
be useful when a user will no longer be using EQUELLA and existing workflow, resource
ownership, ACL expressions and a multitude of other objects can be assigned to another
user.
To change a user ID you need to POST an empty request to .../api/user/[user
id]/action/changeid/[new user id]
E.g.
POST .../api/user/0eaaa6af-dc45-4a58-a21f-ba9089edfcb2/action/changeid/82ccc7ad4ecd-4893-aead-b615074c8270
NOTE: A 200 (success) response can be returned even in the event of failure, since the
task is run in the background.
Re-assign the ID of existing groups

Similarly you can change all references of a group ID to another ID assigned by you. To
do so you will need to POST an empty request to .../group/[group
id]/action/changeid/[new group id]
NOTE: A 200 (success) response can be returned even in the event of failure, since the
task is run in the background.
27 | P a g e
Formats
In the format descriptions below the value types are indicated in triangular brackets (e.g.
<string>).
When POSTing or PUTting a representation some fields are mandatory. In the format
descriptions below mandatory fields are prefixed with *
All dates fields are in ISO 8601 format (http://en.wikipedia.org/wiki/ISO_8601).
NOTE: The following formats may be expanded in the future. Not all fields may be
present in any given representation.
Search Results Representation

Note that the Search Results Representation is used on several endpoints and the results
array may not contain Resource Representations, but the representation type relevant to
the endpoint. E.g. the results field is an array of Notification Representations on the
.../api/notification endpoint.
{
"start": <int>,
"length": <int>,
"available": <int>,
"results": [ <Resource Representation>, ...
Resource Representation
Note that the name and description fields are read-only. If you post a resource
representation to the server, the name and description will be extracted from the
metadata XML, not the name and description fields.
{
"uuid" : <uuid>,
"version" : <int>,
"name" : <string>,
"description" : <string>,
"metadata" : <string>,
"status" : <string>
"createdDate" : <date>,
"modifiedDate" : <date>,
"owner" : <User Representation>,
"collaborators" : [ <User Representation>, ... ],
* "collection" : <Collection Representation>,
"rating" : <float>,
"attachments" : [ <Attachment Representation>, ... ],
"navigation" : <Navigation Representation>,
"drm" : <DRM Representation>,
"links" : {
"self" : ".../api/item/[uuid]/[version]/",
"view" : ".../items/[uuid]/[version]/"
}
}
28 | P a g e
Collection Representation
{
* "uuid" : <uuid>
}
Attachment Representation
{
"uuid" : <uuid>,
* "type" : <string>,
* "description" : <string>,
"viewer" : <string>
}
NOTE: An attachment representation may contain additional fields based on the value of
the 'type' field.
The most common attachment type is 'file'.
File Attachment Representation

{
"uuid" : <uuid>,
* "type" : "file",
"viewer" : <string>,
* "filename" : <string>,
"size" : <int>,
"md5" : <string>,
"thumbFilename" : <string>,
"conversion" : <boolean>,
"links" : {
"thumbnail" : ".../thumbs/[uuid]/[version]/[attach uuid]",
"view" : ".../items/[uuid]/[version]/?attachment.uuid=[attach uuid]"
}
}
EQUELLA Resource Attachment Representation

{
* "type" : "linked-resource",
"uuid" : <uuid>,
* "itemUuid" : <uuid>,
* "itemVersion" : <int>,
"resourceType" : "p",
"resourcePath" : "",
"links" : {
}
}
Link Attachment Representation

{
29 | P a g e
* "type" : "url",
"uuid" : <uuid>,
* "url" : <string>,
"disabled" : <boolean>,
"links" : {
}
}
Web Page Attachment Representation

{
* "type" : "htmlpage",
"uuid" : <uuid>,
"size" : <int>,
"links" : {
}
}
Google Books Attachment Representation

{
* "type" : "googlebook",
"uuid" : <uuid>,
"bookId" : <string>,
"viewUrl" : <string>,
"thumbUrl" : <string>,
"publishedDate" : <string>,
"pages" : <string>,
"links" : {
}
}
YouTube Attachment Representation

{
* "type" : "youtube",
"uuid" : <uuid>,
"videoId" : <string>,
"uploader" : <string>,
"uploadedDate" : <date>,
"tags" : <string>,
"duration" : <int>,
"links" : {
30 | P a g e
}
}
Flickr Attachment Representation

{
* "type" : "flickr",
"uuid" : <uuid>,
"author" : <string>,
"datePosted" : <date>,
"dateTaken" : <date>,
"licenseName" : <string>,
"licenseCode" : <string>,
"licenseKey" : <string>,
"photoId" : <string>,
"mediumUrl" : <string>,
"links" : {
}
}
iTunesU Attachment Representation

{
* "type" : "itunesu",
"uuid" : <uuid>,
* "playUrl" : <string>,
"trackName" : <string>,
"links" : {
}
}
Package Resource Attachment Representation

{
* "type" : "package-res",
"uuid" : <uuid>,
"size" : <int>,
"links" : {
}
}
Content Package Attachment Representation

{
* "type" : "package",
"uuid" : <uuid>,
31 | P a g e
"size" : <int>,
* "packageFile" : <string>,
"links" : {
}
}
Kaltura Attachment Representation

{
* "type" : "kaltura",
"uuid" : <uuid>,
"mediaId" : <string>,
"title" : <string>,
"uploadedDate" : <date>,
"dataUrl" : <string>,
"tags" : <string>,
"duration" : <int>,
"links" : {
}
}
Comment Representation
{
"uuid" : <uuid>,
"rating" : <int>,
"anonymous" : <boolean>,
"comment" : <string>,
"postedBy" : <User Representation>,
"postedDate" : <date>
}
History Event Representation

{
"user" : <User Representation>,
"date" : <date>,
"step" : <uuid>,
"toStep" : <uuid>,
"stepName" : <string>,
"toStepName" : <string>,
"comment" : <string>,
"type" : <string>,
"state" : <string>
}
User Representation
{
* "id" : <string>,
"username" : <string>,
32 | P a g e
"firstName" : <string>,
"lastName" : <string>,
"emailAddress" : <string>
}
File Area Representation

{
"type" : "root",
"filename" : "",
"parent" : "",
"files" : [ <File Representation>, ... ],
"folders" : [ <Directory Representation>, ... ],
"uuid" : <uuid>,
"links" : {
"content" : ".../api/file/[uuid]/content",
"dir" : ".../api/file/[uuid]/dir",
"self" : ".../api/file/[uuid]/dir"
}
}
Directory Representation
{
"type" : "folder",
"filename" : <string>,
"parent" : <string>,
"files" : [ <File Representation>, ... ],
"folders" : [ <Directory Representation>, ... ],
"links" : {
"content" : ".../api/file/[uuid]/content/[path]",
"dir" : ".../api/file/[uuid]/dir/[path]",
"self" : ".../api/file/[uuid]/dir/[path]"
}
}
File Representation
{
"type" : "file",
"filename" : <string>,
"parent" : <string>,
"size" : <int>
"links" : {
"content" : ".../api/file/[uuid]/content/[path]",
"dir" : ".../api/file/[uuid]/dir/[path]",
"self" : ".../api/file/[uuid]/dir/[path]"
}
}
Lock Representation
{
"uuid": <uuid>,
"user": <User Representation>,
"links": [{
"self": ".../api/item/[uuid]/[version]/lock/"
}]
}
33 | P a g e
Navigation Representation
NOTE: showUnreferencedAttachments is deprecated due to faulty reverse Boolean logic
being applied, and is maintained for compatibility only. The new field is
hideUnreferencedAttachments
{
"showUnreferencedAttachments" : <boolean>,
"hideUnreferencedAttachments" : <boolean>,
"showSplitOption" : <boolean>,
"nodes" : [ <Navigation Node Representation>, ... ]
}
Navigation Node Representation

{
"uuid" : <uuid>,
"name" : <string>,
"icon" : <string>,
"imsId" : <string>,
"tabs" : [ <Navigation Tab Representation>, ... ],
"nodes" : [ <Navigation Node Representation>, ... ]
}
Navigation Tab Representation

{
"name" : <string>,
"viewer" : <string>,
"$ref" : <UUID Reference>
}
UUID Reference
{
"$ref" : <uuid>
}
DRM Representation
{
"options" : <DRM Options Representation>
}
DRM Options Representation

{
"drmPageUuid" : <string>,
"hideLicencesFromOwner" : <boolean>,
"showLicenceCount" : <boolean>,
"allowSummary" : <boolean>,
"ownerMustAccept" : <boolean>,
"studentsMustAcceptIfInCompilation" : <boolean>,
"previewAllowed" : <boolean>,
"attributionOfOwnership" : <boolean>,
"enforceAttribution" : <boolean>,
34 | P a g e
"contentOwners" : [ <DRM Party Representation>, ... ],

"usages" : [ <string>, ... ],
"termsOfAgreement" : <string>,
"requireAcceptanceFrom" : <string>,
"restriction" : <DRM Restrictions Representation>
}
DRM Party Representation

{
"userId" : <string>,
"name" : <string>,
"email" : <string>,
"owner" : <boolean>
}
DRM Restrictions Representation

{
"network" : <DRM Network Representation>,
"startDate" : <date>,
"endDate" : <date>,
"usersExpression" : [ <string>, ... ],
"educationalSector" : <boolean>,
"maximumUsage" : <int>
}
DRM Network Representation

{
"name" : <string>,
"startAddress" : <string>,
"endAddress" : <string>
}
Notification Representation
{
"id" : <int>,
"reason" : <string>,
"userTo" : <string>,
"date" : <date>,
"item" : <Resource Representation>
}
Task Status Representation

{
"task" : <Task Representation>,
"item" : <Resource Representation>,
"assignedTo" : <User Representation>,
"dueDate" :<date>,
"startDate" : <date>,
"overdue" : <boolean>
}
35 | P a g e
Task Representation
{
"uuid" : <uuid>,
"name" : <string>,
"priority" : <int>,
"unanimous : <boolean>,
"workflow" : <Workflow Representation>
}
Workflow Representation
{
"uuid" : <uuid>,
"name" : <string>
}
Connector Representation
{
"uuid" : <uuid>,
"name" : <string>,
"type" : <string>
}
Connector Content Representation

{
"id" : <string>,
"course" : <string>,
"courseCode" : <string>,
"courseId" : <string>,
"dateAdded" : <date>,
"folder" : <string>,
"externalTitle" : <string>,
"externalDescription" : <string>
}
Search Definition Representation

{
"id" : <string>,
"name" : <string>
}
Examples
Resource Example
{
"uuid" : "2f6e9be8-897d-45f1-98ea-7aa31b449c0e",
"version" : 1,
"name" : "ItemApiViewTest - All attachments",
36 | P a g e
"metadata" : "<xml><item><attachments><attachment1>63862d54-1b6d-4dce-9a7944b3a8c9e107</attachment1><attachment1>32f45d7c-6df7-44d8-926a3d6f841c2009</attachment1><attachment1>32a79ea6-8b67-4b38-af85341b2d512f09</attachment1><attachment1>78a2de74-96de-48de-886522856c22ae49</attachment1><attachment1>b24aa5fa-de50-4021-b7c4ac4d3a918129</attachment1><attachment1>dd26b4ac-9592-4062-bd15cb9691bfe9a3</attachment1><attachment1>221b8a48-3a35-4d29-ad3a0f04a1536b3b</attachment1><attachment1>20196bbc-7f5f-44a4-980d55dab4e6eec9</attachment1><attachment1>034dfcb7-b66a-45bf-98c803da9011c74d</attachment1></attachments><name>ItemApiViewTest - All

attachments</name></item></xml>",
"status" : "live",
"createdDate" : "2012-02-23T17:57:25.615-06:00",
"modifiedDate" : "2012-02-23T23:27:53.107-06:00",
"owner" : {
"id" : "adfcaf58-241b-4eca-9740-6a26d1c3dd58"
},
"collaborators" : [ {
"id" : "c4c9471b-d3e1-4157-9847-2e6d1e8b9b4e"
} ],
"collection" : {
"uuid" : "9a1ddb24-6bf5-db3d-d8fe-4fca20ecf69c"
},
"rating" : 5.0,
"attachments" : [ {
"type" : "file",
"uuid" : "63862d54-1b6d-4dce-9a79-44b3a8c9e107",
"description" : "avatar.png",
"viewer" : "livNavTreeViewer",
"filename" : "avatar.png",
"size" : 12627,
"md5" : "5a4e69eeae86aa557c4a27d52257b757",
"thumbFilename" : "_THUMBS/avatar.png.jpeg",
"conversion" : false,
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/63862d54-1b6d-4dce-9a79-44b3a8c9e107",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=63862d54-1b6d-4dce-9a79-44b3a8c9e107"
}
}, {
"type" : "linked-resource",
"uuid" : "32f45d7c-6df7-44d8-926a-3d6f841c2009",
"description" : "SearchStemming - Walking",
"itemUuid" : "072c40d8-c8a8-412d-8ad2-3ef188ea016d",
"itemVersion" : 1,
"resourceType" : "p",
"resourcePath" : "",
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/32f45d7c-6df7-44d8-926a-3d6f841c2009",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=32f45d7c-6df7-44d8-926a-3d6f841c2009"
}
}, {
"type" : "url",
"uuid" : "32a79ea6-8b67-4b38-af85-341b2d512f09",
37 | P a g e
"description" : "Google",
"url" : "http://google.com.au/",
"disabled" : false,
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/32a79ea6-8b67-4b38-af85-341b2d512f09",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=32a79ea6-8b67-4b38-af85-341b2d512f09"
}
}, {
"type" : "htmlpage",
"uuid" : "78a2de74-96de-48de-8865-22856c22ae49",
"description" : "Web Page",
"filename" : "_mypages/78a2de74-96de-48de-8865-22856c22ae49/page.html",
"size" : 24,
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/78a2de74-96de-48de-8865-22856c22ae49",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=78a2de74-96de-48de-8865-22856c22ae49"
}
}, {
"type" : "googlebook",
"uuid" : "b24aa5fa-de50-4021-b7c4-ac4d3a918129",
"description" : "Book!",
"bookId" : "http://www.google.com/books/feeds/volumes/NBMDtWq1MnUC",
"viewUrl" : "http://books.google.com/books?id=NBMDtWq1MnUC&ie=ISO-88591&source=gbs_gdata",
"thumbUrl" :
"http://bks6.books.google.com/books?id=NBMDtWq1MnUC&printsec=frontcover&img=1&zoo
m=5&edge=curl&source=gbs_gdata",
"publishedDate" : "2001-09-17",
"pages" : "44",
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/b24aa5fa-de50-4021-b7c4-ac4d3a918129",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=b24aa5fa-de50-4021-b7c4-ac4d3a918129"
}
}, {
"type" : "youtube",
"uuid" : "dd26b4ac-9592-4062-bd15-cb9691bfe9a3",
"description" : "Test Your Awareness: Do The Test",
"videoId" : "Ahg6qcgoay4",
"uploader" : "dothetest",
"uploadedDate" : "2008-03-10T12:30:17.000-05:00",
"viewUrl" :
"http://www.youtube.com/v/Ahg6qcgoay4?version=3&f=videos&c=EQUELLA&app=youtube_gd
ata",
"thumbUrl" : "http://i.ytimg.com/vi/Ahg6qcgoay4/default.jpg",
"tags" : "test, awareness, basketball, visual, do, the, attention, span,
bike, ad, cycling, TFL, safety, moonwalking, bear",
"duration" : 69,
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/dd26b4ac-9592-4062-bd15-cb9691bfe9a3",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea-
38 | P a g e
7aa31b449c0e/1/?attachment.uuid=dd26b4ac-9592-4062-bd15-cb9691bfe9a3"
}
}, {
"type" : "flickr",
"uuid" : "221b8a48-3a35-4d29-ad3a-0f04a1536b3b",
"description" : "Gold C64",
"author" : "FRaNKy--",
"datePosted" : "2006-10-23T14:46:16.000-05:00",
"dateTaken" : "2006-10-20T21:50:12.000-05:00",
"licenseName" : "All Rights Reserved",
"viewUrl" : "http://flickr.com/photos/19017538@N00/277527331",
"thumbUrl" : "http://farm1.staticflickr.com/88/277527331_ab0fa4348e_t.jpg",
"licenseCode" : "not-for-display",
"licenseKey" : "0",
"photoId" : "277527331",
"mediumUrl" : "http://farm1.staticflickr.com/88/277527331_ab0fa4348e.jpg",
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/221b8a48-3a35-4d29-ad3a-0f04a1536b3b",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=221b8a48-3a35-4d29-ad3a-0f04a1536b3b"
}
}, {
"type" : "itunesu",
"uuid" : "20196bbc-7f5f-44a4-980d-55dab4e6eec9",
"description" : "SGA Roundup 01-31-11",
"playUrl" :
"http://deimos.apple.com/WebObjects/Core.woa/Browsev2/utm.edu.6530144102",
"trackName" : "SGA Roundup 01-31-11",
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/20196bbc-7f5f-44a4-980d-55dab4e6eec9",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=20196bbc-7f5f-44a4-980d-55dab4e6eec9"
}
}, {
"type" : "package-res",
"uuid" : "bb4f8b1d-8760-4082-a4bc-c3cea9ad0ce7",
"description" : "index.html",
"filename" : "The vile vendor go figure.zip/index.html",
"size" : 0,
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/bb4f8b1d-8760-4082-a4bc-c3cea9ad0ce7",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=bb4f8b1d-8760-4082-a4bc-c3cea9ad0ce7"
}
}, {
"type" : "package",
"uuid" : "034dfcb7-b66a-45bf-98c8-03da9011c74d",
"description" : "The vile vendor: go figure",
"size" : 21718,
"packageFile" : "The vile vendor go figure.zip",
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/034dfcb7-b66a-45bf-98c8-03da9011c74d",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea-
39 | P a g e
7aa31b449c0e/1/?attachment.uuid=034dfcb7-b66a-45bf-98c8-03da9011c74d"
}
}, {
"type" : "package-res",
"uuid" : "6553c4bf-38f1-43f5-a58a-91ddfa4ff30f",
"description" : "index.html",
"filename" : "The vile vendor go figure.zip/index.html",
"size" : 0,
"links" : {
"thumbnail" : "http://institution.edu/thumbs/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/6553c4bf-38f1-43f5-a58a-91ddfa4ff30f",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/?attachment.uuid=6553c4bf-38f1-43f5-a58a-91ddfa4ff30f"
}
} ],
"navigation" : {
"showUnreferencedAttachments" : false,
"showSplitOption" : false,
"nodes" : [ {
"uuid" : "49ffd9d1-cc47-4fce-ae49-897ca0a54024",
"name" : "avatar.png",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "63862d54-1b6d-4dce-9a79-44b3a8c9e107"
},
"viewer" : ""
} ],
"nodes" : [ {
"uuid" : "44d6eaa6-1a1a-4cff-94d9-31e8bb871d73",
"name" : "Book!",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "b24aa5fa-de50-4021-b7c4-ac4d3a918129"
},
"viewer" : ""
} ],
"nodes" : [ {
"uuid" : "fadf767b-9715-4e33-80fb-ac49bce869ae",
"name" : "Web Page",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "78a2de74-96de-48de-8865-22856c22ae49"
},
"viewer" : ""
} ],
"nodes" : [ ]
} ]
} ]
}, {
"uuid" : "0cc07c84-fba7-491f-970b-2abb623ac962",
"name" : "Gold C64",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
40 | P a g e
"$ref" : "221b8a48-3a35-4d29-ad3a-0f04a1536b3b"
},
"viewer" : ""
} ],
"nodes" : [ {
"uuid" : "4961186a-7bb1-46ca-a0b9-a92ec7cd5777",
"name" : "Google",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "32a79ea6-8b67-4b38-af85-341b2d512f09"
},
"viewer" : ""
} ],
"nodes" : [ ]
} ]
}, {
"uuid" : "f074109b-e0fa-4404-9296-848a12034ff5",
"name" : "SearchStemming - Walking",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "32f45d7c-6df7-44d8-926a-3d6f841c2009"
},
"viewer" : ""
}, {
"name" : "Tab 2",
"attachment" : {
"$ref" : "63862d54-1b6d-4dce-9a79-44b3a8c9e107"
},
"viewer" : ""
} ],
"nodes" : [ {
"uuid" : "4ef8419a-1d76-478e-b58c-80022fedf4ce",
"name" : "Test Your Awareness: Do The Test",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "dd26b4ac-9592-4062-bd15-cb9691bfe9a3"
},
"viewer" : ""
} ],
"nodes" : [ {
"uuid" : "529882e2-16ce-46c3-bd87-b66f4365c49f",
"name" : "SGA Roundup 01-31-11",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "20196bbc-7f5f-44a4-980d-55dab4e6eec9"
},
"viewer" : ""
} ],
"nodes" : [ ]
} ]
} ]
}, {
"uuid" : "89b8bbd5-8d67-4ae5-a531-b4b8e2957cf2",
41 | P a g e
"name" : "The vile vendor: go figure",

"tabs" : [ ],
"nodes" : [ {
"uuid" : "6f5a50eb-3c28-4dcb-bf99-615b6715ea37",
"name" : "Start: The vile vendor: go figure",
"imsId" : "O41860I0",
"tabs" : [ {
"name" : "Auto Created By IMS Viewer",
"attachment" : {
"$ref" : "6553c4bf-38f1-43f5-a58a-91ddfa4ff30f"
},
"viewer" : ""
} ],
"nodes" : [ ]
} ]
}, {
"uuid" : "4441d5fe-9941-412f-9674-3f860a44fb5b",
"name" : "index.html",
"tabs" : [ {
"name" : "Tab 1",
"attachment" : {
"$ref" : "bb4f8b1d-8760-4082-a4bc-c3cea9ad0ce7"
},
"viewer" : ""
} ],
"nodes" : [ ]
} ]
},
"links" : {
"self" : "http://institution.edu/api/item/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/",
"view" : "http://institution.edu/items/2f6e9be8-897d-45f1-98ea7aa31b449c0e/1/"
}
}
Internal REST API Reference

An internal REST API reference page displays information about all available REST
endpoints and the operations and parameters supported for each endpoint. It also
displays a link to the EQUELLA REST API Guide.
Open the REST API reference

1. Open a browser and enter the EQUELLA address of the hosting server including the
institution name with /apidocs.do appended to the URL. (e.g.
http://equella.myinstitution.edu/institution/logon.do would become
http://equella.myinstitute.edu/institution/apidocs.do). The EQUELLA REST API page
displays. An example is shown in Figure 6.
42 | P a g e
Figure 6 EQUELLA REST API page

2. If you wish to try out the GET methods, you will need to login to EQUELLA as a user
with appropriate resource discovery privileges.
The EQUELLA REST API reference lists Endpoints (search, item-lock, item-action, item,
file and item-relation). Each endpoint has the following links:
Show/Hide toggles the operations list for each endpoint.
List Operations lists the available operations for each endpoint.
Expand Operations lists the available operations for each endpoint with a
parameter dialog.
An example of the search end point operation search parameter dialog is shown in
Figure 7.
43 | P a g e
Figure 7 search end point 'search' operation parameter dialog

Enter parameters and click
shown in Figure 8.
to display the result of the operation. An example is
44 | P a g e
Figure 8 Results of search operation
45 | P a g e
Contact Client Support

We are always happy to help.
If your organisation has a support agreement with EQUELLA then help is available at
http://equella.custhelp.com.
46 | P a g e

Equella 6.1 Rest API Guide

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Equella 6.1 Rest API Guide

Hochgeladen von

Copyright:

Verfügbare Formate

EQUELLA

REST API Guide

May 2013 edition.

Contact documentation@equella.com for matters relating to documentation.

EQUELLA 6.1 REST API Guide

EQUELLA 6.1 REST API Guide

Retrieving tasks ......................................................................................................... 25

EQUELLA 6.1 REST API Guide

EQUELLA REST API

would refer to:

where 5950e6b8-6ce4-11e1-b335-fb4e4824019b is a UUID of a resource and 2 is the

EQUELLA 6.1 REST API Guide

OAuth Client Configuration

Accessing OAuth settings

To access the OAuth settings page

EQUELLA 6.1 REST API Guide

Figure 1 OAuth settings page

Registering OAuth client applications

To register a new Oauth client

Figure 2 Create new OAuth client page

EQUELLA 6.1 REST API Guide

To Configure an OAuth Client for Authorisation Code Grant

Figure 3 Authorisation code grant options

To configure an OAuth Client for Implicit Grant

EQUELLA 6.1 REST API Guide

Figure 4 Implicit grant options

To configure an OAuth Client for Client Credentials Grant

EQUELLA 6.1 REST API Guide

Figure 5 Client credentials grant and LTI authentication

Obtaining An OAuth Token

Obtaining a token via Authorization Code Grant

EQUELLA 6.1 REST API Guide

1. Your application must redirect to the OAuth authorisation endpoint

which could be acheived by:

where a token will returned in JSON format. For example,

Your application must extract the access_token value.

Obtaining a token via Implicit Grant

EQUELLA 6.1 REST API Guide

Obtaining a token via Client Credentials Grant

a token will returned in JSON format. . E.g.

Your application must extract the access_token value.

EQUELLA 6.1 REST API Guide

Searching for Resources

q - The search query. Default value is blank.

collections - A comma separated list of collection UUIDs. Default behaviour is to

"like" | "not like" | "in" | "not in"

EQUELLA 6.1 REST API Guide

'basic' returns resource names and descriptions.

'metadata' will return the resource metadata xml.

'attachment' will return the list of attachments on each resource.

'all' returns all of the above, limited by the user's privileges.

Searching personal resources

Retrieving available search types

Performing a personal resources search

EQUELLA 6.1 REST API Guide

Using the 'where' parameter (/xml/item/pagecount in (1,2,3,4)), returning

EQUELLA 6.1 REST API Guide

Attempting to perform a GET on .../api/item without a UUID will result in an error.

Requesting specific details

EQUELLA 6.1 REST API Guide

The resource history is read-only.

EQUELLA 6.1 REST API Guide

Contributing a New Resource

The directory structure will be created as required.