HandcarRelationshipService

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

The Handcar Relationship Service is a RESTful expression of the OSID relationship manager and related services needed to manage
relationships.

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 its rich
functionality.

Known Limitations:

  1. Manipulating Families directly is not yet supported, instead families are created that correspond to objective banks

  2. You cannot store additional information such as name, description or extensions on Parent-Child relationships



OSID reference: Relationship Package

Operations
Main Message Structures

Method getFamilyGenusTypes
Description Gets the list of family genus types.

OSID reference: Family.genusType
REST Signature 
GET handcar/services/relationship/types/genus/family?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 relationship types that can be used to build relationships
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 getRelationshipGenusTypes
Description Gets the list of relationship genus types.

Note: this includes Objective to Objective relationships but may also include other types of relationships between other
kinds of objects.

OSID reference: Relationship.genusType
REST Signature 
GET handcar/services/relationship/families/{familyId}/types/genus/relationship?proxyname={XXXX}
Parameters String familyId id of the family for which these types are configured
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return TypeBeanList list of relationship types that can be used to build relationships
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 bank id does not exist

Back to Operations

Method getCreateFamilyIdForObjectiveBankId
Description Gets the Id of the family of relationships that corresponds to the specified family id

Objectives are organized into "banks" and relationships are organized into "families." They are equivalent concepts. In the
OSIDS they are all called "catalogs."

If such a family does not exist it is created automatically for you.

This method maps between them so we know that these relationships are all connected to the specified bank.
REST Signature 
GET handcar/services/relationship/familyidforbank/{objectiveBankId}?proxyname={XXXX}
Parameters String objectiveBankId the objective id for which the
String proxyName ???
Return String the id of the corresponding family.
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 relationship id is not in the bank

Back to Operations

Method getCreateObjectiveBankIdForFamilyId
Description Gets the Id of the objective bank that corresponds to the specified family id

Objectives are organized into "banks" and relationships are organized into "families." They are equivalent concepts. In the
OSIDS they are all called "catalogs."

If such an objective bank does not exist it is created automatically for you.

This method maps between them so we know that these relationships are all connected to the specified bank.
REST Signature 
GET handcar/services/relationship/bankidforfamily/{familyId}?proxyname={XXXX}
Parameters String familyId the objective id for which the
String proxyName ???
Return String the id of the corresponding bank.
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 relationship id is not in the bank

Back to Operations

Method getFamiliesOptionallyByGenusType
Description Get a list of all relationship families

OSID reference: FamilyLookupSession
REST Signature 
GET handcar/services/relationship/families?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 FamilyBeanList list of all relationship families
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 getFamilyById
Description Get a particular family by id

OSID reference: FamilyLookupSession
REST Signature 
GET handcar/services/relationship/families/{familyId}?proxyname={XXXX}
Parameters String familyId 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 FamilyBean the fetched objective bank
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 family id is bad

Back to Operations

Method getRelationshipsInFamilyOptionallyByGenusType
Description Get relationships in the family
REST Signature 
GET handcar/services/relationship/families/{familyId}/relationships?genustypeid={id}&genustypeid={id}...&proxyname={XXXX}
Parameters String familyId within which the relationships exist
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 RelationshipBeanList list of relationships in this family optionally restricted by genus type
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 relationship id is not in the family

Back to Operations

Method getRelationshipInFamilyById
Description Fetch a particular relationship from a family
REST Signature 
GET handcar/services/relationship/families/{familyId}/relationships/{relationshipId}?proxyname={XXXX}
Parameters String familyId family that the relationship is in
String relationshipId id of the relationship 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 RelationshipBean the fetched relationship
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 relationship id is not in the family

Back to Operations

Method getRelationshipById
Description Fetch a particular relationship regardless of family
REST Signature 
GET handcar/services/relationship/relationships/{relationshipId}?proxyname={XXXX}
Parameters String relationshipId id of the relationship 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 RelationshipBean the fetched relationship
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 relationship id is not in the family

Back to Operations

Method createRelationshipInFamily
Description Creates a relationship in a family
REST Signature 
POST {relationship} to  handcar/services/relationship/families/{familyId}/relationships/?proxyname={XXXX}
{
     "id" : "id",
     "genusTypeId" : "id",
     "displayName" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "description" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "sourceId" : "id",
     "destinationId" : "id",
     "endReasonId" : "id",
     "startDate" : "YYYY-MM-DD",
     "endDate" : "YYYY-MM-DD",
     "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 String familyId within which the relationship is to be created
RelationshipBean relationship to be created
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return RelationshipBean the newly created relationship
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 family or relationship does not exist
HandcarInvalidArgumentException HTTP 422 if the data is invalid

Back to Operations

Method updateRelationshipInFamily
Description Updates an relationship

The relationship Id read-only and cannot be changed and changes will be silently ignored. The source and destination ids
are read-only on updates and cannot be changed (you have to delete the relationship and create a new one instead).

OSID reference: RelationshipAdminSession
REST Signature 
PUT {relationship} to  handcar/services/relationship/families/{familyId}/relationships/?proxyname={XXXX}
{
     "id" : "id",
     "genusTypeId" : "id",
     "displayName" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "description" :  {
          "languageTypeId" : "id",
          "scriptTypeId" : "id",
          "formatTypeId" : "id",
          "text" : "XXXX"
          },
     "sourceId" : "id",
     "destinationId" : "id",
     "endReasonId" : "id",
     "startDate" : "YYYY-MM-DD",
     "endDate" : "YYYY-MM-DD",
     "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 String familyId within which the relationship is to be updated
RelationshipBean relationship to be updated
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return RelationshipBean the newly updated relationship
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 family or relationship does not exist
HandcarInvalidArgumentException HTTP 422 if the data is invalid

Back to Operations

Method deleteRelationshipInFamily
Description Delete an Relationship
REST Signature 
DELETE handcar/services/relationship/families/{familyId}/relationships/{relationshipId}?proxyname={XXXX}
Parameters String familyId within which the relationship exists
String relationshipId id of the relationship to be deleted
String proxyName optional name of user for whom this operation is being executed, if not specified taken from security
context
Return RelationshipBean the relationship 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 relationship is not in the family

Back to Operations