VOOT is a simplified version of OpenSocial and the API is available at: https://voot.surfconext.nl/. The calls described below need to be prepended with this URL.
...
Authorization
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:
Code Block | ||
---|---|---|
| ||
/me/groups
/me/groups/urn:collab:group:surfteams.nl:nl:surfnet:diensten:students |
use SURFconext OpenID Connect to get an access_token. You need at least the scope "groups" to access the Voot API. Ask SURFconext support to configure this for your client. This access_token can be used as a bearer token to get access to the Voot API. For details on how this works, please refer to the SURFconext OIDC playground
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 institution group provider. By default, you will not receive groups from an institution group provider. If you like to use groups from institution group provider, please contact support@surfconext.nl.
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Host: voot.surfconext.nl GET /me/groups HTTP/1.1 Response HTTP/1.1 200 OK Content-Type: application/json [ { "filteredid" : false"urn:collab:group:uniharderwijk.nl:cis", "itemsPerPagedisplayName" : 2, "sortedcis": true, "startIndexdescription" : 0null, "totalResultssourceID" : 2, "updatedSinceUniHarderwijk": false, "entrymembership" : [ { "descriptionbasic" : "Private law working group 2014Q2",member" } }, { "id" : "urn:collab:group:surfteams.nl:nl:surfnet:diensten:privat_law_2014Q2myexampleteam", "titledisplayName" : "Private law 2014Q2MyExampleTeam", "voot_membership_roledescription" : "admin" This team is an }, { example", "descriptionsourceID": null, "id": "urn:collab:group:surfteams.nl:nl:surfnet:diensten:students2014SURFteams", "titlemembership" : "Students started in 2014", { "voot_membership_rolebasic" : "memberadmin" } } ] } |
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.
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
Host: voot.surfconext.nl GET /me/groups/urn:collab:group:surfteams.nl:nl:surfnet:diensten:abc_helpdesk_administrators HTTP/1.1 Response HTTP/1.1 200 OK Content-Type: application/json { "filteredid" : false, "itemsPerPage": 1"urn:collab:group:surfteams.nl:nl:surfnet:diensten:abc_helpdesk_administrators", "sorteddisplayName": false, "startIndex": 0, "totalResults": 1, "updatedSince": false"ABC helpdesk administrators", "entry": [ { "description"description" : "Administrators of the ABC helpdesk service.", "idsourceID" : "nl:surfnet:diensten:abc_helpdesk_administratorsSURFteams", "titlemembership" : "ABC helpdesk administrators",{ "voot_membership_role""basic" : "admin" } ] } |
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
Code Block | ||||
---|---|---|---|---|
| ||||
/me/groups/urn:collab:group:surfteams.nl:nl:surfnet:diensten:privat_law_2014Q2?startIndex=3&count=2 /me/groups?sortBy=title |
Response parameters
...
...
...
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:
...
Retrieve Group Membership
...
- 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