Changes between Version 16 and Version 17 of UniformClearinghouseAPIV2


Ignore:
Timestamp:
11/12/13 12:51:36 (10 years ago)
Author:
mbrinn@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPIV2

    v16 v17  
    573573NB: SLICE_NAME must adhere to the restrictions for slice names in the Aggregate Manager (AM) API, namely that it must be <= 19 characters, only alphanumeric plus hyphen, no leading hyphen.
    574574
    575 {{{
    576 #!python
    577 # Provide details on the version, services and options supported by this SA
    578 #
    579 # Arguments:
    580 #    Options:
    581 #
    582 # Return:
    583 #   get_version structure information as described above
    584 def get_version()
    585 }}}
    586 
    587 {{{
    588 #!python
    589 # Create a new slice, optionally within a project. See generic create_* method description above.
    590 #
    591 # Arguments:
    592 #
    593 #   Options:
    594 #       'fields', a dictionary field/value pairs for object to be created
    595 #
    596 # Return:
    597 #   Dictionary of field/value pairs for created slice (e.g. slice URN, slice UUID, expiration and slice credential)
    598 #
    599 # Should return DUPLICATE_ERROR if creating a slice for which a non-expired slice of same name exists.
    600 def create_slice (credentials, options)
    601 }}}
    602 
    603 {{{
    604 #!python
    605 # Lookup slice detail for slices matching ‘match’ options.
    606 #
    607 # ‘filter’ options indicate what detail to provide. See generic lookup_* method description above.
    608 #
    609 # Arguments:
    610 #    options: What details to provide (filter options) for which slices (match options)
    611 #
    612 # Return: List of dictionaries with field/value pairs for each returned slice
    613 #
    614 def lookup_slices (credentials, options)
    615 }}}
    616 
    617 {{{
    618 #!python
    619 # Update fields in given slice object. See generic update_* method description above.
    620 #
    621 # Arguments:
    622 #   slice_urn: URN of slice to update
    623 #
    624 #    Options: Contains ‘fields’ key referring dictionary of name/value pairs to update
    625 # Return: None
    626 #
    627 def update_slice(slice_urn, credentials, options)
    628 }}}
     575The Sliver Info Service supports these standard API methods for type="SLIVER_INFO", with elaboration in the following table:
     576
     577|| ''' Method ''' || ''' Description ''' ||
     578|| create || Creates a  new slice with provided details  ||
     579|| update || Updates given slice ||
     580|| --delete-- || Note: No SA should support slice deletion since there is no authoritative way to know that there aren't live slivers associated with that slice.  ||
     581|| lookup || lookup slicesmatching given match criteria subject to authorization restrictions. ||
     582
     583Additionally, the Slice service provides the following methods:
    629584
    630585{{{
     
    650605The set of recognized role types (e.g. LEAD, ADMIN, MEMBER, OPERATOR, AUDITOR) are to be listed in the get_version for a given Slice Authority.
    651606
    652 {{{
    653 #!python
    654 # Modify slice membership, adding, removing and changing roles of members with respect to given slice
    655 #
    656 # Arguments:
    657 #   Slice_urn: URN of slice for which to modify membership
     607The following methods are written generically (with type arguments) to support the Slice Member Service as well as the Project Member Service (below).
     608
     609{{{
     610#!python
     611# Modify object membership, adding, removing and changing roles of members with respect to given object
     612#
     613# Arguments:
     614#   type: type of object for whom to lookup membership (in the case of Slice Member Service, "SLICE", in the case of Project Member Service, "PROJECT")
     615#   urn: URN of slice/project for which to modify membership
    658616#   Options:
    659 #       members_to_add: List of member_urn/role tuples for members to add to slice of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
    660 #       members_to_remove: List of member_urn of members to remove from slice
    661 #       members_to_change: List of member_urn/role tuples for members whose role should change as specified for given slice of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
     617#       members_to_add: List of member_urn/role tuples for members to add to slice/project of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role} (or 'PROJECT_MEMBER/PROJECT_ROLE for Project Member Service)
     618#       members_to_remove: List of member_urn of members to remove from slice/project
     619#       members_to_change: List of member_urn/role tuples for members whose role should change as specified for given slice/project of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role} (or 'PROJECT_MEMBER/PROJECT_ROLE for Project Member Service)
    662620#
    663621# Return:
    664622#   None
    665 def modify_slice_membership(slice_urn, credentials, options)
    666 }}}
    667 
    668 {{{
    669 #!python
    670 # Lookup members of given slice and their roles within that slice
    671 #
    672 # Arguments:
    673 #   slice_urn: URN of slice for which to provide current members and roles
    674 #
    675 # Return:
    676 #    List of dictionaries of member_urn/role pairs [{‘SLICE_MEMBER’: member_urn, ‘SLICE_ROLE’: role }...] where ‘role’ is a string of the role name
    677 def lookup_slice_members(slice_urn, credentials, options)
    678 }}}
    679 
    680 {{{
    681 #!python
    682 # Lookup slices for which the given member belongs
     623def modify_membership(type, urn, credentials, options)
     624}}}
     625
     626{{{
     627#!python
     628# Lookup members of given object and their roles within that object
     629#
     630# Arguments:
     631#   type: type of object for whom to lookup membership (in the case of Slice Member Service, "SLICE", in the case of Project Member Service, "PROJECT")
     632#   urn: URN of object for which to provide current members and roles
     633#
     634# Return:
     635#    List of dictionaries of member_urn/role pairs [{‘SLICE_MEMBER’: member_urn, ‘SLICE_ROLE’: role }...] (or PROJECT_MEMBER/PROJECT_ROLE for Project Member Service) where ‘role’ is a string of the role name.
     636def lookup_members(type, urn, credentials, options)
     637}}}
     638
     639{{{
     640#!python
     641# Lookup objects of given type for which the given member belongs
    683642#
    684643# Arguments:
     
    686645#
    687646# Return:
    688 #    List of dictionary of slice_urn/role pairs [(‘SLICE_URN’ : slice_urn, ‘SLICE_ROLE’ : role} ...] for each slice to which a member belongs, where role is a string of the role name
    689 def lookup_slices_for_member(member_urn, credentials, options)
     647#    List of dictionary of urn/role pairs [(‘SLICE_URN’ : slice_urn, ‘SLICE_ROLE’ : role} ...] (or PROJECT_MEMBER/PROJECT_ROLE for Project Member Service) for each object to which a member belongs, where role is a string of the role name
     648def lookup_for_member(type, member_urn, credentials, options)
    690649}}}
    691650
     
    706665|| SLIVER_INFO_CREATION || DATETIME || Time of sliver creation || No || Allowed || No ||
    707666
    708 {{{
    709 #!python
    710 # Create a record of a sliver creation
    711 #
    712 # Arguments:
    713 #   options: 'fields' containing the fields for the sliver info  being registered at SA
    714 #
    715 # Return:
    716 # Dictionary of name/value pairs for created sliver_info record
    717 def create_sliver_info(credentials, options)
    718 }}}
    719 
    720 {{{
    721 #!python
    722 # Delete a sliver_info record
    723 #
    724 # Arguments:
    725 #    sliver_urn: urn of sliver whose record is to be deleted
    726 #
    727 # Return:
    728 #   True if succeeded
    729 #
    730 #Should return ARGUMENT_ERROR if no such sliver urn is registered
    731 def delete_sliver_info(sliver_urn, credentials, options)
    732 }}}
    733 
    734 {{{
    735 #!python
    736 # Update the details of a sliver_info record
    737 #
    738 #Arguments:
    739 #   sliver_urn: urn of sliver for which to update
    740 #   options: 'fields' containing fields for sliver_infos that are permitted for update
    741 #
    742 # Return:
    743 #   None
    744 #
    745 # Should return ARGUMENT_ERROR if no such sliver_urn is found
    746 def update_sliver_info(sliver_urn, credentials, options)
    747 }}}
    748 
    749 {{{
    750 #!python
    751 # Lookup sliver_info for given match criteria return fields in given filter criteria
    752 #
    753 # Arguments:
    754 #   options: 'match' for query match criteria, 'filter' for fields to be returned
    755 #
    756 # Return:
    757 #    Dictionary (indexed by sliver_urn) of dictionaries containing name/value pairs for all sliver_infos registered at this SA matching given criteria.
    758 def lookup_sliver_info(credentials, options)
    759 }}}
     667The Sliver Info Service supports these standard API methods for type="SLIVER_INFO", with elaboration in the following table:
     668
     669|| ''' Method ''' || ''' Description ''' ||
     670|| create || Registers  new sliver info with provided details  ||
     671|| update || Updates given sliver info ||
     672|| delete || Deletes given sliver info ||
     673|| lookup || lookup sliver info matching given match criteria subject to authorization restrictions. ||
     674
    760675
    761676== Project Service Methods ==
     
    774689|| PROJECT_DESCRIPTION || STRING || Description of Project || No || Allowed || Yes ||
    775690
    776 {{{
    777 #!python
    778 # Create project with given details. See generic create_* description above.
    779 #
    780 # Arguments:
    781 #   Options: 'fields', a dictionary of name/value pairs for newly created project.
    782 #
    783 # Return:
    784 #   Dictionary of name/value pairs of newly created project including urn
    785 #
    786 #Should return DUPLICATE_ERROR if creating a project for which a project of same name exists.
    787 def create_project(credentials, options)
    788 }}}
    789 
    790 {{{
    791 #!python
    792 # Lookup project detail for projects matching ‘match options.
    793 # ‘filter options indicate what detail to provide.
    794 #
    795 # Arguments:
    796 #    options: What details to provide (filter options) for which members (match options)
    797 #
    798 # Return:
    799 #    Dictionary of name/value pairs from ‘filter’ options for each project matching ‘match’ option criteria.
    800 def lookup_projects(credentials, options)
    801 }}}
    802 
    803 {{{
    804 #!python
    805 # Update fields in given project object, as allowed in Get_version advertisement. See generic update_* description above.
    806 #
    807 # Arguments:
    808 #    project_urn: URN of project to update
    809 #    Options: Contains ‘fields’ key referencing dictionary of key/value pairs to update project
    810 #
    811 # Return: None
    812 def update_project(project_urn, credentials, options)
    813 }}}
     691The Project Service supports these standard API methods for type="PROJECT", with elaboration in the following table:
     692
     693|| ''' Method ''' || ''' Description ''' ||
     694|| create || Creates a new project with provided details  ||
     695|| update || Updates given project ||
     696|| delete || Deletes given project. Note: should fail if there are any active slices associated with project. ||
     697|| lookup || lookup projects matching given match criteria subject to authorization restrictions. ||
     698
    814699
    815700== Project Member Service Methods ==
    816701
    817 Projects may have members associated with them in particular roles. See the Slice Member Service Methods above for more description.
    818 
    819 {{{
    820 #!python
    821 # Modify project membership, adding, removing and changing roles of members with respect to given project
    822 #
    823 # Arguments:
    824 #   project_urn: Name of project for which to modify membership
    825 #   Options:
    826 #      members_to_add: List of member_urn/role tuples for members to add to project of form {‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’ : role}
    827 #      members_to_remove: List of member_urn of members to remove from project
    828 #      members_to_change: List of member_urn/role tuples for members whose role should change as specified for given project of form {‘PROJECT_MEMBER’ : member_urn, ‘PROJECT_ROLE’ : role}
    829 #
    830 # Return:  None
    831 def modify_project_membership(project_urn, credentials, options)
    832 }}}
    833 
    834 {{{
    835 #!python
    836 # Lookup members of given project and their roles within that project
    837 #
    838 # Arguments:
    839 #    project_urn: project_urn for which to provide current members and roles
    840 #
    841 #Return:
    842 #   List of dictionaries of member_urn/role pairs of form [{‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’: role}...]
    843 def lookup_project_members (project_urn, credentials, options)
    844 }}}
    845 
    846 {{{
    847 #!python
    848 # Lookup projects for which the given member belongs
    849 #
    850 # Arguments:
    851 #    Member_urn: The member for whom to find project to which it belongs
    852 #
    853 # Return:
    854 #    Dictionary of slice_urn/role pairs (‘PROJECT_URN’ : project_urn, ‘PROJECT_ROLE’ : role} where role is a string of the role name
    855 def lookup_projects_for_member(member_urn, credentials, options)
    856 }}}
     702Projects may have members associated with them in particular roles and thus supports the same methods for member management as described above for the Slice Member Service. The differences are that the type provide is "PROJECT", the urn provided is a project URN and the membership information returned is tagged with "PROJECT_URN' and 'PROJECT_ROLE' as appropriate.
     703
     704|| ''' Method ''' || ''' Description ''' ||
     705|| modify_membership || Adds/removes/changes roles of members with respect to given project   ||
     706|| lookup_members || Returns list of {PROJECT_MEMBER, PROJECT_ROLE} dictionaries| for members projects matching given criteria ||
     707|| lookup_for_member || Returns list of {PROJECT_URN, PROJECT_RULE} dictionaries for projects to which a given member belongs ||
     708
    857709
    858710== Member Authority API ==