HandcarHierarchyService

Key HandcarHierarchy
Version 1.0
Included Services  
Java Package edu.mit.oeit.mc3.handcar.model

The Handcar Hierarchy Service is a RESTful expression of the OSID hierarchy manager.

The hierarchy's accessed via this server all are implemented by making calls to the relationship service. So these two services
are two sides of the same coin. Changes here are reflected in the hierarchy service and changes made via the relationship
service are reflected here.

These items are known issues that are under consideration for implementation in future releases.

  1. Free form querying using keywords to find nodes is not supported



Handcar is a simplified, but faithful, expression of the OSIDs that aligns with the REST goals of simplicity and focuses on
exposing OSID objects as resources.

See Wikipedia Representation state transfer

In particular Handcar takes a data centric view whereas the OSIDS exercise more specific method calls to express it's rich
functionality. For example, whereas the OSIDS allow a consumer to add and remove individual parents or children in a node
hierarchy, this RESTful expression allows only complete updates replacing any existing parents or children with the new set of
parents or children.

OSID reference: Hierarchy Manager Package

Operations
Main Message Structures

Method getAuthorizationHints
Description Get authorization hints
REST Signature 
GET handcar/services/hierarchy/authorization?proxyname={XXXX}
Parameters String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return AuthorizationHintsBean authorization hints for accessing hierarchies
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user

Back to Operations

Method getAuthorizationHintsForHierarchy
Description Get authorization hints for a particular hierarchy
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/authorization?proxyname={XXXX}
Parameters String hierarchyId that you want to fetch
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return AuthorizationHintsBean authorization hints for accessing hierarchies
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user

Back to Operations

Method getHierarchiesOptionallyByGenusType
Description Get a list of all hierarchies

OSID reference: HierarchyLookupSession
REST Signature 
GET handcar/services/hierarchy/hierarchies?genustypeid={id}&genustypeid={id}...&proxyname={XXXX}
Parameters StringList genusTypeIds optional list of genus types on which to query
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return HierarchyBeanList list of all hierarchies
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user

Back to Operations

Method getHierarchyById
Description Get a particular hierarchy by id

OSID reference: HierarchyLookupSession
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}?proxyname={XXXX}
Parameters String hierarchyId that you want to fetch
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return HierarchyBean the fetched hierarchy
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy id is bad

Back to Operations

Method createHierarchy
Description Creates an hierarchy

Note: for certain hierarchy genus types there can only be one hierarchy with that type. If you try to create another one
the pre-existing one is returned instead.

OSID reference: HierarchyAdminSession
REST Signature 
POST {hierarchy} to  handcar/services/hierarchy/hierarchies?proxyname={XXXX}
{
     "id" : "id",
     "genusTypeId" : "id",
     "displayName" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "description" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "current" : true,
     "sortKey" : "XXXX",
     "extensionRecord" :  {
          "recordTypeIds" : ["id", ...],
          "recordProperties" : [ {
               "displayName" :  {
                    "languageTypeId" : "id",
                    "scriptTypeId" : "id",
                    "formatTypeId" : "id",
                    "text" : "XXXX"
                    },
               "description" :  {
                    "languageTypeId" : "id",
                    "scriptTypeId" : "id",
                    "formatTypeId" : "id",
                    "text" : "XXXX"
                    },
               "recordTypeId" : "id",
               "value" : "XXXX",
               "displayLabel" :  {
                    "languageTypeId" : "id",
                    "scriptTypeId" : "id",
                    "formatTypeId" : "id",
                    "text" : "XXXX"
                    },
               "associatedId" : "id"
               },
               ...],
          "associatedId" : "id"
          },
     "auditTrail" :  {
          "addedBy" : "XXXX",
          "addedOn" : "YYYY-MM-DDThh:mm:ss",
          "updatedBy" : "XXXX",
          "updatedOn" : "YYYY-MM-DDThh:mm:ss",
          "comment" : "XXXX"
          }
}
Parameters HierarchyBean hierarchy to be created
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return HierarchyBean the newly created hierarchy
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException ???
HandcarInvalidArgumentException HTTP 422 if the data is invalid

Back to Operations

Method updateHierarchy
Description Updates an hierarchy

OSID reference: HierarchyAdminSession
REST Signature 
PUT {hierarchy} to  handcar/services/hierarchy/hierarchies?proxyname={XXXX}
{
     "id" : "id",
     "genusTypeId" : "id",
     "displayName" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "description" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "current" : true,
     "sortKey" : "XXXX",
     "extensionRecord" :  {
          "recordTypeIds" : ["id", ...],
          "recordProperties" : [ {
               "displayName" :  {
                    "languageTypeId" : "id",
                    "scriptTypeId" : "id",
                    "formatTypeId" : "id",
                    "text" : "XXXX"
                    },
               "description" :  {
                    "languageTypeId" : "id",
                    "scriptTypeId" : "id",
                    "formatTypeId" : "id",
                    "text" : "XXXX"
                    },
               "recordTypeId" : "id",
               "value" : "XXXX",
               "displayLabel" :  {
                    "languageTypeId" : "id",
                    "scriptTypeId" : "id",
                    "formatTypeId" : "id",
                    "text" : "XXXX"
                    },
               "associatedId" : "id"
               },
               ...],
          "associatedId" : "id"
          },
     "auditTrail" :  {
          "addedBy" : "XXXX",
          "addedOn" : "YYYY-MM-DDThh:mm:ss",
          "updatedBy" : "XXXX",
          "updatedOn" : "YYYY-MM-DDThh:mm:ss",
          "comment" : "XXXX"
          }
}
Parameters HierarchyBean hierarchy to be updated
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return HierarchyBean the newly updated hierarchy
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy or node does not exist
HandcarInvalidArgumentException HTTP 422 if the data is invalid

Back to Operations

Method deleteHierarchy
Description Delete an Hierarchy

OSID reference: HierarchyAdminSession
REST Signature 
DELETE handcar/services/hierarchy/hierarchies/{hierarchyId}?proxyname={XXXX}
Parameters String hierarchyId id of hierarchy to be deleted
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return HierarchyBean the hierarchy as it was before it was deleted
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the node is not in the hierarchy

Back to Operations

Method getHierarchyExtensionRecord
Description Fetch a particular hierarchy's extension record

An EXTENSION record is basically a set of key value pairs holding additional data not explicitly defined in the object. It
is a way to extend the object without breaking the contract. See ExtensionRecordBean
for more details.

OSID reference: Hierarchy.getHierarchyRecord
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/extension?recordtypeid={id}&recordtypeid={id}...&proxyname={XXXX}
Parameters String hierarchyId hierarchy who's extension is to be fetched
StringList optionalRecordTypeIds optional list of the record types to include, if not specified all record types are included
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return ExtensionRecordBean the fetched hierarchy's extension
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy id is not valid

Back to Operations

Method updateHierarchyExtensionRecord
Description Update a particular hierarchy's extension record

An EXTENSION record is basically a set of key value pairs holding additional data not explicitly defined in the object. It
is a way to extend the object without breaking the contract. See ExtensionRecordBean
for more details.

OSID reference: Hierarchy.getHierarchyRecord
REST Signature 
PUT {extensionRecord} to  handcar/services/hierarchy/hierarchies/{hierarchyId}/extension?proxyname={XXXX}
{
     "recordTypeIds" : ["id", ...],
     "recordProperties" : [ {
          "displayName" :  {
               "languageTypeId" : "id",
               "scriptTypeId" : "id",
               "formatTypeId" : "id",
               "text" : "XXXX"
               },
          "description" :  {
               "languageTypeId" : "id",
               "scriptTypeId" : "id",
               "formatTypeId" : "id",
               "text" : "XXXX"
               },
          "recordTypeId" : "id",
          "value" : "XXXX",
          "displayLabel" :  {
               "languageTypeId" : "id",
               "scriptTypeId" : "id",
               "formatTypeId" : "id",
               "text" : "XXXX"
               },
          "associatedId" : "id"
          },
          ...],
     "associatedId" : "id"
}
Parameters String hierarchyId hierarchy who's extension is to be fetched
ExtensionRecordBean extensionRecord extension record to replace the existing extension record
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return ExtensionRecordBean the hierarchies extension once updated
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy id is not valid

Back to Operations

Method getHierarchyBranding
Description Fetch a particular hierarchy's branding information

OSID reference: Sourceable
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/branding?proxyname={XXXX}
Implementation Notes not implemented yet
Parameters String hierarchyId id of hierarchy who's branding information is to be fetched
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return BrandingBean the fetched hierarchy's branding information
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy id is not valid

Back to Operations

Method getRootIds
Description Fetch the root ids in the hierarchy

OSID reference: HierarchyTraversalSession
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/root/ids?proxyname={XXXX}
Parameters String hierarchyId hierarchy for which you wish to fetch the root nodes
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return IdsBean the ids of the root nodes for this hierarchy
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy id does not exist

Back to Operations

Method updateRootIds
Description Add the list of ids as roots

Makes the supplied list of ids roots

Note: the ordering of the list will NOT be preserved when fetched, see getRootIds

OSID reference: HierarchyDesignSession
REST Signature 
PUT {ids} to  handcar/services/hierarchy/hierarchies/{hierarchyId}/root/ids?proxyname={XXXX}
{
     "ids" : ["id", ...]
}
Parameters String hierarchyId within which the node is to be updated
IdsBean ids bean holding an list of ids to be used in this update
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return IdsBean the newly updated list of ids
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy or node or any of the ids do not exist

Back to Operations

Method getRootNodes
Description Fetch the root nodes for this hierarchy and optionally it's children down to a specified depth

OSID reference: HierarchyTraversalSession
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/root/nodes?descendentlevels={999}&proxyname={XXXX}
Parameters String hierarchyId hierarchy for which you wish to fetch the root nodes
Integer descendentLevels number of levels down to fetch if not specified then 10 levels are fetched
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return NodeBeanList the root node nodes for this hierarchy down to the specified depth
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy id does not exist

Back to Operations

Method getParentIds
Description Fetch a particular node's hierarchy parent ids

See also getParents

To maintain this list see updateChildIds


An example of a hierarchy could be:

Math
  Arithmetic
     Addition
     Subtraction
     Multiplication
     Division
  Geometry
     Planes
     Lines
     Angles
  Calculus


Parent and child are the same relationship just viewed from the opposite perspective. See also href="#HandcarHierarchy-getChildIds">getChildIds

Typically an node has just a single parent but we discovered situations where the same topic naturally aligns under
different parents so the contract allows for multiple parents.

OSID reference: HierarchyTraversalSession
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/parent/ids/{id}?proxyname={XXXX}
Parameters String hierarchyId hierarchy that the node is in
String id id of the node you want to fetch
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return IdsBean the node's parent's ids
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the node id is not in the hierarchy

Back to Operations

Method getChildIds
Description Fetch a particular node's hierarchy child ids

See also getChildren

Parent and child are the same relationship just viewed from the opposite perspective. See also href="#HandcarHierarchy-getParentIds">getParentIds

To maintain this list see updateChildIds

OSID reference: HierarchySession
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/child/ids/{id}?proxyname={XXXX}
Parameters String hierarchyId hierarchy that the node is in
String id id of the node you want to fetch
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return IdsBean the node's children's ids
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the node id is not in the hierarchy

Back to Operations

Method updateChildIds
Description Updates an node's children by specifying their ids

Makes the supplied list of ids the children of this node.

Note: the ordering of the list will NOT be preserved when fetched, see getChildIds

OSID reference: HierarchyDesignSession
REST Signature 
PUT {ids} to  handcar/services/hierarchy/hierarchies/{hierarchyId}/child/ids/{id}?proxyname={XXXX}
{
     "ids" : ["id", ...]
}
Parameters String hierarchyId within which the node is to be updated
String id whose children are to be updated
IdsBean ids bean holding an list of ids to be used in this update
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return IdsBean the newly updated list of ids
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the hierarchy or node or any of the ids do not exist

Back to Operations

Method getChildNodes
Description Bulk operation to fetch nodes representing a particular node's children, grandchildren, great-grandchildren, etc.

See also getChildren

OSID reference: HierarchySession.getNodes
REST Signature 
GET handcar/services/hierarchy/hierarchies/{hierarchyId}/child/nodes/{id}?descendentlevels={999}&proxyname={XXXX}
Parameters String hierarchyId hierarchy that the node is in
String id id of the node you want to fetch
Integer descendentLevels number of levels down to fetch if not specified then 10 levels are fetched
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return NodeBean a node holding the node's children, and grand children down to the specified depth
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the node id is not in the hierarchy

Back to Operations

Method getHierarchyGenusTypes
Description Gets the list of supported hierarchy genus types.

These types are the same as the relationship genus types used to manage the paarent-child relationship

OSID reference: Hierarchy.genusType
REST Signature 
GET handcar/services/hierarchy/hierarchies/types/genus?proxyname={XXXX}
Parameters String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return TypeBeanList list of genus types that can be applied to an hierarchy
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user

Back to Operations

Method getTypeById
Description Get a particular type by id regardless of the hierarchy

This can be any kind of type, genus, format, script, language, etc

OSID reference: Hierarchy.genusType
REST Signature 
GET handcar/services/hierarchy/types/{typeId}?proxyname={XXXX}
Parameters String typeId id of the type you want to fetch
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return TypeBean type that can be applied to an hierarchy
Errors HandcarOperationFailedException HTTP 500 if something goes wrong
HandcarPermissionDeniedException HTTP 403 if you don't have rights to call this method or are not allowed to proxy
user
HandcarNotFoundException HTTP 404 if the type id does not exist

Back to Operations