Use API with Java

On this page guidelines are described that will help developers to connect Java applications as SP to OpenConext and use the OpenConext API.

The OpenConext API is a web service and is hosted by OpenConext. With it, you can retrieve user, group memberships and group information from OpenConext. It is a REST web service which means that the subjects and actions you request are part of the URL you send. The OpenConext API will return the result as a JSON structure.

The OpenConext API supports the following calls:

1. Retrieve a user's personal information.
2. Retrieve a list of groups the user is a member of.
3. Retrieve the members of a group.
4. Retrieve information of a group

You can only retrieve information for a user when he has at least logged in once using OpenConext. Group information is taken from the connected group providers like OpenConext Teams.

More information about the OpenConext API can be found in the OpenConext API pages.

An existing Java source can be used as interface to connect to OpenConext. The source can be found here: https://github.com/OpenConext/OpenConext-api/tree/master/coin-api-client

Apart from the actual REST interface, this module contains an OAuth 'form-based' client, capable of making the following configurable OAuth calls:

• 2-legged and 3-legged OAuth1.0a
• OAuth2.0 authorization code grant and implicit grant
• OAuth2.0 access token requests using either query parameters, entity body parameters or the authorization header Step by step detail information about the OAuth requests and responses
• Implementing the OpenConext OpenSocial API

The OpenConext OpenSocial API can be implemented using Java or via Spring XML.

Implementing the OpenConext OAuth Clien class using Java:

OpenConextOAuthClient api = new OpenConextOAuthClientImpl();    
api.setEndpointBaseUrl("https://api.demo.openconext.org/v1/");
// (1)     api.setConsumerKey("key");    
api.setConsumerSecret("secret");     
api.getPerson("urn:collab:person:test.surfguest.nl:gvanderploeg", null);

Using Spring XML:

<bean id="apiClient" class="nl.surfnet.coin.api.client.OpenConextOAuthClientImpl">  
  <property name="endpointBaseUrl" value="${api-location}" />  
  <property name="consumerKey" value="${oauth-key}"/>  
  <property name="consumerSecret" value="${oauth-secret}" />
  <property name="version" value="v10a" />
</bean>

This will result in the following:

{
  "startIndex":0,
  "totalResults":1,
  "itemsPerPage":1,
  "filtered":false,
  "updatedSince":false,
  "sorted":false,
  "entry": {
    "nickname":"Geert van der Ploeg",
    "emails":[{"value":"[email protected]","type":"email"}],
    "id":"urn:collab:person:test.surfguest.nl:gvanderploeg",
    "name":{"formatted":"Geert van der Ploeg","familyName":"van der Ploeg","givenName":"Geert"},
    "tags":["guest"],
    "accounts":[{"username":"gvanderploeg","userId":"gvanderploeg"}],
    "displayName":"Geert van der Ploeg",
    "voot_membership_role":null,
    "organizations":[{"name":"test.surfguest.nl","type":null,"department":null,"title":null}],
    "phoneNumbers":null,
    "error":null
  }
}