uPortal's REST API

uPortal has a rich RESTful web service based API that returns JSON. Here are the paths to those services. This document assumes that you deploy your uPortal instance to the /uPortal context. This list is incomplete as not the whole API is public facing.

[GET] /uPortal/api/session.json

This is the session feed that will return information under the object "person". This gives you things like the username, displayName, sessionKey, and version.

[GET] /uPortal/api/people.json?searchTerms=xxx&searchTerms=yyy

Returns information about people. User must have VIEW access on the user attributes.

The API has a list of search terms and search values. These are what's called the 'seed' (horrible term) that's passed into classes defined in personDirectoryContext.xml for searching. Typically the search terms are passed along to an LDAP search with an OR configuration (which is how personDirectoryContext.xml is normally configured, see https://wiki.jasig.org/display/UPM43/LDAP+User+Attribute+Sources). You can also review https://wiki.jasig.org/display/UPM43/Configuring+Search but it is more for the portal's Search not specifically for a person search. So a search of

/uPortal/api/people.json?searchTerms%5B%5D=givenName&searchTerms%5B%5D=sn&searchTerms%5B%5D=username&givenName=student&sn=student&username=student

this is saying search terms are givenName and username, and the values of both are student (and typically you have your LDAP search configured for OR comparisons; e.g. givenName=student OR username=student).

Permissions drive what attributes are allowed to be released to what type of user, and which users can be included in search results. For example in the 'default' uPortal 4.3.0 configuration:

users that are included and excluded from search: https://github.com/Jasig/uPortal/blob/uportal-4.3.0/uportal-war/src/main/data/default_entities/permission_set/Authenticated_Users__VIEW_USER__UP_USERS.permission-set.xml
Attributes allowed to be returned to what type of user (everyone in the default case but you could have different results for guest vs. authenticated, or staff/faculty vs. student): https://github.com/Jasig/uPortal/blob/uportal-4.3.0/uportal-war/src/main/data/default_entities/permission_set/Everyone__VIEW_USER_ATTRIBUTE__UP_USERS.permission-set.xml

[GET] /uPortal/api/people/{username}.json

Returns information about people. User must have VIEW access to the user and to specified user attributes. See additional information above.

[GET] /uPortal/layout.json (also at uPortal/api/v1/dlm/layout.json)

This provides your whole layout with folder (aka tab) structures and everything. Does not include regions, favorites, or favorite collections.

For new development consider using /uPortal/api/v4.3/dlm/layout.json instead.

[GET] /uPortal/api/v4-3/dlm/layout.json) (uPortal 4.3+)

This provides your whole layout with folder (aka tab) structures and everything including regions, favorites, favorite collections, portlet publishing parameters, and certain UI information (are impersonating, can add tab, etc.).

[GET] /uPortal/api/layoutDoc

Parameters: tab (optional)

If tab is not provided, it returns an array of all the current users portlets.

If the tab is provided, it returns that tab's portlets.

This meta data can be useful for drawing layouts on a main page or in a menu.

[GET] /uPortal/api/marketplace/entries.json

This fetches a list of entries that is available in the app store/marketplace in your uPortal instance. This does take into account permissions with BROWSE and SUBSCRIBE for that user.

[GET] /uPortal/api/marketplace/entry/{fname}.json

Path Parameter : fname = the functional name of the portlet

This fetches the meta data for a specific portlet.

[POST] /uPortal/api/marketplace/{fname}/getRating

This fetches a rating for a given user for that portlet.

/uPortal/api/marketplace/{fname}/rating/{rating}

Path Parameter:

fname : the functional name of the portlet
rating : the rating the user wishes to post

Request Parameter:

review : The review text you wish to add to the rating (optional)

[POST] /uPortal/api/layout?action={action}

This is how you modify your layout. Each action has different things that are required and its kind of complex. So I'm going to just point you at the Java file. You can find that here.