You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

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 value surfteams.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 of Group identifier
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
Example
Host: voot.surfconext.nl
GET /me/groups HTTP/1.1
 
Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "filtered": false,
  "itemsPerPage": 2,
  "sorted": true,
  "startIndex": 0,
  "totalResults": 2,
  "updatedSince": false,
  "entry": [
    {
      "description": "Private law working group 2014Q2",
      "id": "urn:collab:group:surfteams.nl:nl:surfnet:diensten:privat_law_2014Q2",
      "title": "Private law 2014Q2",
      "voot_membership_role": "admin"
    },
    {
      "description": null,
      "id": "urn:collab:group:surfteams.nl:nl:surfnet:diensten:students2014",
      "title": "Students started in 2014",
      "voot_membership_role": "member"
    }
  ]
}

Get group information

Group information is taken from SURFconext Teams.

/me/groups/{groupId}

{groupId} must be replaced with a SURFconext group identifier (to be obtained with 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.

Example of Get group information
Host: voot.surfconext.nl
GET /me/groups/nl:surfnet:diensten:abc_helpdesk_administrators HTTP/1.1
 
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 calls can have three parameters:

  • startIndex
    determines the offset as the start for giving back results.
  • count
    number of results to be returned.  
  • sortBy
    determines the key for sorting groups. Possible values: id, title, description.
    note that the members of a group cannot be sorted
    sorting MUST be performed before startIndex and count

 

Example
/me/groups/urn:collab:group:surfteams.nl:nl:surfnet:diensten:privat_law_2014Q2?startIndex=3&count=2
/me/groups?sortBy=title

Response parameters

  • filtered
    always false (SURFconext does not support filters).  
  • sorted
    false unless the request contained a sortBy parameter.
  • startIndex
    offset from which the results are returned (usually equal to the requested startIndex).  
  • 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 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 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;
  • If the specified user does not exist at the provider an error response with code 404 Not Found is returned. The error field contains invalid_user;
  • If any other error occurs an error response with code 500 Internal Server Error is returned. The error field contains internal_server_error
  • No labels