Tags Administration. REST API

Owned by Former user (Deleted)
Nov 02, 2017
4 min read

 

1. REST API

The tag service has a rest API that allows other tools to search it, and allows the admin user or any administrative tool to be integrated with the system to manage the existing tags and collections.

There are two different rest entry points:

  • tagservice

  • tagservice-admin

The first rest entry point is public.  The second rest entry point needs a specific token and only admin users are allowed to use it.



2. TAGSERVICE

This is the public tagservice that any tool can use for query. The service works with Spring injection, as an alternative way to work, but for javascript components to display tags, as the one used in Samigo, this provides a better way to query the tag service.

This service has the following four calls:

  • getTagsPaginatedByPrefixInLabel : list (GET) : [/tagservice/getTagsPaginatedByPrefixInLabel] (json)

  • getPaginatedTagCollections : list (GET) : [/tagservice/getPaginatedTagCollections] (json)

  • getTagsPaginatedInCollection : list (GET) : [/tagservice/getTagsPaginatedInCollection] (json)

  • getTag : list (GET) : [/tagservice/getTag] (json)


Every call that has the “paginated” word on it accepts these 2 parameters:

  • page: The page number used for pagination

  • pagelimit : The number of results per page (it will be limited by the tagservice.maxpagesize property in the sakai.properties file. If this is not set, the default max value is 200)


This is a sample call using these values:

If “page” or “pagelimit” is not specified, the first page with the default pagelimit value is returned.


2.1 getTagsPaginatedByPrefixInLabel

The following example returns the results when searching for tags that start with the prefix parameter.  

direct/tagservice/getTagsPaginatedByPrefixInLabel.json?prefix=Lo

Will search for any tag with a label starting with “Lo” (it is not case sensitive)

Parameters:

  • prefix : The string to search by.



2.2 getPaginatedTagCollections

This example returns the available tag collections in the system.

direct/tagservice/getPaginatedTagCollections.json

Parameters:

No parameters




2.3 getTagsPaginatedInCollection

The following example shows how to return the tags from a collection.  

direct/tagservice/getTagsPaginatedInCollection.json?tagcollectionid=a267923b  -9eed-417f-9656-5f801f1164b6

Parameters:

  • tagcollectionid: To know the id, It can be retrieved from the getPaginatedTagCollections


2.4 getTag

This example returns all the information from a single tag

tagservice/getTag.json?tagid=c5bc6575-ec2e-4278-aa2a-0dc899bd2512

Parameters:

  • tagId: To know the id, It can be retrieved from the getTagsPaginatedInCollection or the getTagsPaginatedByPrefixInLabel


3. TAGSERVICE-ADMIN

The tagservice-admin endpoint will be used only by admin users to manage the tag collections.

To access this endpoint a sakai session needs to be opened and the correct token needs to be provided.

To create this token, you can use the startSession call for a user with this permission: tagservice.manage in the /site/!admin

The token created can be used later while the user session is active. The next part of this document provides an example for using the endpoint.

This API contains the following calls for the endpoint:

  • startSession : new (POST) : [/tagservice-admin/startSession]

  • updateTag : edit (PUT) : [/tagservice-admin/:ID:/updateTag]

  • downloadCollection : list (GET) : [/tagservice-admin/downloadCollection] (json) (xml)

  • deleteTag : new (POST) : [/tagservice-admin/deleteTag]

  • createTag : new (POST) : [/tagservice-admin/createTag]

  • deleteTagCollection : new (POST) : [/tagservice-admin/deleteTagCollection]

  • createTagCollection : new (POST) : [/tagservice-admin/createTagCollection]

  • updateTagCollection : edit (PUT) : [/tagservice-admin/:ID:/updateTagCollection]


As stated earlier, except for startSession, every call will need to have:

  • sessionid : the session Id returned by the startSession call.



3.1 startSession (POST)

To get the token, first open a normal rest session. It is not enough to open it with a browser, a call needs to be made to this service:

https://YOURSERVERURL/direct/session?_username=XXXX&_password=XXXX

Provide the user information to access later.

Once completed (a sessionId will be returned but it can be ignored because the cookie that has been generated will be used) call the startSession with the POST:

direct/tagservice-admin/startSession/

a response will be received as shown below:

{"session":"53bc9e0a8da58d4bf6cfc096a5c92b874ef0448c1f979717ec145d782ff39bd5"}

This id will be used in the following calls as session


3.2 createTagCollection (POST)

Creates a new tag collection using:

direct/tagservice-admin/createTagCollection.json

Parameters:

  • name: The collection name to display to the users. Mandatory

  • description : The description for the tag collection.

  • externalsourcename : The external source name for the collection.  This is not a mandatory parameter but it is required to be used in the synchronization jobs. 

  • externalsourcedescription: A description about where this collection comes from.

  • externalcreation : 1 or 0, Indicates if this is supposed to be created by an external system or not. This will be used to allow the users in the UI to modify or not modify the collection.

  • externalupdate: 1 or 0, Indicates if this is supposed to be updated by an external system or not. This will be used to allow to the users in the UI to modify or not modify the collection.

  • lastsynchronizationdate: The last date (milliseconds format)  this collection was updated from the external source. (this can be useful in the synchronization jobs).

  • lastupdatedateinexternalsystem: The last date this collection was updated in the external system (this can be useful in the synchronization jobs).

  • session: The session identifier (sessionId).



3.3 createTag (POST)

Creates a new tag:

direct/tagservice-admin/createTag.json

Parameters:

  • taglabel:  The tag label to display to the users. Mandatory

  • tagcollectionid:  The collection id containing the tag. Mandatory

  • description : The tag description.

  • externalid : The identifier the external source uses to identify the tag. This is not a mandatory parameter but it is required to be used in the synchronization jobs.

  • alternativelabels: Other labels for the same tag. Some collections use this.

  • externalcreation : 1 or 0, Indicates if this is supposed to be created by an external system or not. This will be used to allow to the users in the UI to modify or not modify the collection

  • externalupdate: 1 or 0, Indicates if this is supposed to be updated by an external system or not. This will be used to allow to the users in the UI to modify or not modify the collection

  • lastupdatedateinexternalsystem: The last date where this collection was updated in the external system (this can be useful in the synchronization jobs)

  • parentid : The ID of the tag that is the parent of this tag, in case a hierarchy is to be created

  • externalhierarchycode: The external hierarchy information. Some collections have specific hierarchy codes. It is only informative.

  • externaltype: Some collections have different types. It is only informative.

  • data: Extra information that can be stored for a tag. It is only informative.

  • session: The session identifier (sessionId).



3.4. deleteTag (POST)

Deletes a tag:

/tagservice-admin/deleteTag

Parameters:

  • id: The tag id to delete.

  • session: The session identifier (sessionId).


3.5. updateTag (POST)

Updates the values in an existing tag:

/tagservice-admin/updateTag

Parameters:

  • id: The tag id to update.

  • Additional parameters are the same as createTag.



3.6. updateTagCollection (POST)

Updates the values in an existing tag collection:

/tagservice-admin/updateTagCollection

Parameters:

  • tagcollectionid: The tag collection id to update.

  • Additional parameters are the same as createTagCollection.



3.7. deleteTagCollection (POST)

Deletes a tag collection:

/tagservice-admin/deleteTagCollection

Parameters:

  • id: The tag collection id to delete.

  • session: The session identifier (sessionId).


3.8 downloadCollection (GET)

Downloads a full collection in an xml format. This file can be used later to update the collection (edit the file and use the sakai quartz job to read it).

/direct/tagservice-admin/downloadCollection.xml

  • tagcollectionid: The tag collection id to update.

  • session: The session identifier (sessionId).