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.
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:
@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.@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 |
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.
urn:collab:group:{group_provider}:{group_name} |
group_provider
: name of the group provider (surfteams.nl or the name of an institution group provider, it has the name of that institution 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
/me/groups |
Host: voot.surfconext.nl GET /me/groups HTTP/1.1 Response HTTP/1.1 200 OK Content-Type: application/json [ { "id" : "urn:collab:group:uniharderwijk.nl:cis", "displayName" : "cis", "description" : null, "sourceID" : "UniHarderwijk", "membership" : { "basic" : "member" } }, { "id" : "urn:collab:group:surfteams.nl:nl:surfnet:diensten:myexampleteam", "displayName" : "MyExampleTeam", "description" : "This team is an example", "sourceID" : "SURFteams", "membership" : { "basic" : "admin" } } ] |
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).
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 { "id" : "urn:collab:group:surfteams.nl:nl:surfnet:diensten:abc_helpdesk_administrators", "displayName" : "ABC helpdesk administrators", "description" : "Administrators of the ABC helpdesk service.", "sourceID" : "SURFteams", "membership" : { "basic" : "admin" } } |
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", } |
@me
an error response with code 404 Not Found
is returned. The error
field contains invalid_user
. If a user identifier is specified instead of @me
for providers not supporting the use of user identifiers the same error is returned;404 Not Found
is returned. The error
field contains invalid_user
;500 Internal Server Error
is returned. The error
field contains internal_server_error