VOOT is a web service hosted by SURFconext, allowing you to retrieve information about users, groups and group memberships. VOOT is a simplified version of OpenSocial and is available at: https://voot.surfconext.nl/. The calls described below need to be prepended with this URL.
User identifier
You can retrieve information for a user when he has at least logged in once using SURFconext. For the API calls, the client has to specify the user identifier for which the information is retrieved:
- For API calls using OAuth 2.0 and OAuth 1.0a three-legged, you must use the
@me
placeholder. This is replaced in the provider with the actual user identifier. In this way the client does not need to know the unique identifier of the user in SURFconext. - For OAuth 1.0a two-legged authentication, you must specify an actual user and group identifier:
@me
is not supported.
If the user john
authorized a client to act on its behalf, with an OAuth 2.0 or OAuth 1.0a three-legged authentication the following calls are defined:
/me/groups /me/groups/urn:collab:group:surfteams.nl:nl:surfnet:diensten:students
Group identifier
With VOOT you can request information about a group or a user's group memberships. The groups can be from SURFconext Teams or an external group provider. By default, you will not receive groups from an external group provider, unless you added this to your Production environment connection request.
urn:collab:group:{group_provider}:{group_name}
group_provider
: name of the group provider (surfteams.nl or the name of an external group provider, it has the name of that external group provider).group_name
: name of the group within the group provider.
urn:collab:group:surfteams.nl:nl:surfnet:diensten:SURFconext_admins urn:collab:group:avans.nl:nl.avans.AVANS-employee_grp
Supported calls
Get a user's group membership
/me/groups
Get group information
Group information is taken from SURFconext Teams. This call will only return the group's information if the user is a member of this group.
/me/groups/{groupId}
{groupId}
must be replaced with a SURFconext group identifier (to be obtained with the user's group membership call).
Request parameters
The calls can have three parameters:
startIndex
offset as the start for giving back results.- count
number of results to be returned. sortBy
key for sorting groups. Possible values:id,
title,
description.
note that the members of a group cannot be sorted
sorting MUST be performed beforestartIndex
andcount
/me/groups/urn:collab:group:surfteams.nl:nl:surfnet:diensten:privat_law_2014Q2?startIndex=3&count=2 /me/groups?sortBy=title
Response parameters
- filtered
alwaysfalse
(SURFconext does not support filters). - sorted
false
unless the request contained asortBy
parameter. - startIndex
offset from which the results are returned (usually equal to the requestedstartIndex)
. - itemsPerPage
actual number of results in the response set, as part of entry, returned. - totalResults
total number of elements, independend of startIndex and count parameters. - updatedSince
always false. - entry
list of items: groups, people or person information.
Errors
Handling failures of OAuth (Bearer) authentication are handled as described in [RFC 6750]. This will involve sending the WWW-Authenticate
header if something is wrong, for example an invalid OAuth 2.0 access token will result in the following response:
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="Resource Server",error="invalid_token",error_description="the access token is not valid" Content-Type: application/json {"error":"invalid_token","error_description":"the access token is not valid"}
There are also some request errors defined, i.e.: invalid requests to SURFconext that are dealt with in a certain manner. The error response is returned as JSON, for example:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "invalid_user", }
Retrieve Group Membership
- If OAuth v1.0a two-legged authentication is used with
@me
an error response with code404 Not Found
is returned. Theerror
field containsinvalid_user
. If a user identifier is specified instead of@me
for providers not supporting the use of user identifiers the same error is returned; - If the specified user does not exist at the provider an error response with code
404 Not Found
is returned. Theerror
field containsinvalid_user
; - If any other error occurs an error response with code
500 Internal Server Error
is returned. Theerror
field containsinternal_server_error