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/. All calls mentioned 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, the
@me
placeholder identifier must be used. This is replaced in the provider with the actual user identifier that authorized the client to act on its behalf. With this placeholder, the client does not need to know the unique identifier of the user in SURFconext. - For OAuth 1.0a two-legged authentication an actual user identifier and group identifier must be specified,
@me
is not supported here due to the lack of binding with an user that authorized the client to act on its behalf. It is out of scope how the client obtains the identifiers of the user or group.
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.
If the group is made in SURFconext Teams, it has the valuesurfteams.nl
. If the group is from an external group provider, it has the name of that external group provider.group_name
: name of the group within the group provider.
Examples:
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.
/me/groups/{groupId}
Where you need to replace {groupId}
with a SURFconext group identifier which could have been obtained through the user's group membership call.
This call will only return the group's information if the authenticated user is a member of this group.
The response contains the information of the requested group.
Example request
Example response
HTTP/ 1.1 200 OK Content-Type: application/json { "filtered" : false , "itemsPerPage" : 1 , "sorted" : false , "startIndex" : 0 , "totalResults" : 1 , "updatedSince" : false , "entry" : [ { "description" : "Administrators of the ABC helpdesk service." , "id" : "nl:surfnet:diensten:abc_helpdesk_administrators" , "title" : "ABC helpdesk administrators" , "voot_membership_role" : "admin" } ] } |
Request parameters
The SURFconext API calls can have three OPTIONAL parameters that manipulate the result:
startIndex
count
sortBy
The sortBy
parameter determines the key in the result that is used for sorting groups. Default sorting for groups is by id
. It can be any of these keys:
id
title
description
If you use a key that is not available in the set being sorted, the results are not sorted.
It is currently not possible to sort the result of a request for the members of a group
The startIndex
parameter determines the offset as an integer >= 0 as the start for giving back results. The count
parameter, an integer >= 0 indicates the number of results to be returned. The startIndex
and count
parameters can be used to implement paging by returning only a subset of the results. These parameters are OPTIONAL, if they are not provided or invalid, startIndex
is considered equal to 0
and count
equal to the total number of items available in the entire result set.
The sorting, if requested, MUST be performed on the provider before applying limiting the results based on the startIndex
andcount
parameters.
For the API call, requesting user information, the sortBy
parameter has no effect. Using startIndex
and count
is possible, however they are of little use as there always will be only one answer, assuming the user exists.
Some example of using request parameters:
/me/groups?sortBy=title |
Response parameters
All responses mentioned above have the same JSON structure. There are always seven keys:
- filtered
- sorted
- startIndex
itemsPerPage
totalResults
updatedSince
entry
The key filtered
is always false
as SURFconext does not support filters. The sorted key is false
unless the request contained a sortBy
parameter, in that case it is true
.
Where startIndex
contains the offset from which the results are returned, this is usually equal to the requested startIndex
. The itemsPerPage
contains the actual number of results in the response set, as part of entry
, returned. The totalResults
field contains the full number of elements available, not depending on the startIndex
and count
parameters.
The updatedSince
key always has the value false
.
The entry
key contains a list of items, either groups, people or person information.
See the examples in the Supported calls section.
Errors
Handling failures of OAuth (Bearer) authentication are handled in the ways 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
The call looks like this:
/me/groups
- 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