Changes between Version 70 and Version 71 of UniformClearinghouseAPI


Ignore:
Timestamp:
09/26/13 16:11:36 (10 years ago)
Author:
mbrinn@bbn.com
Comment:

Convert API formatting to python formatting for increased readability

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPI

    v70 v71  
    476476NB: 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.
    477477
    478 /*
    479 
    480 Provide details on the version, services and options supported by this SA
    481 
    482 '''Arguments:'''
    483 
    484 Options:
    485 
    486 '''Return:'''
    487 
    488 get_version structure information as described above
    489 
    490 */
    491 
    492 function '''get_version()'''
    493 
    494 /*
    495 
    496 Create a new slice, optionally within a project. See generic create_* method description above.
    497 
    498 '''Arguments:'''
    499 
    500 Options: 'fields', a dictionary field/value pairs for object to be created
    501 
    502 '''Return:''' Dictionary of field/value pairs for created slice (e.g. slice URN, slice UUID, expiration and slice credential)
    503 
    504 Should return DUPLICATE_ERROR if creating a slice for which a non-expired slice of same name exists.
    505 
    506 
    507 */
    508 
    509 function '''create_slice''' (credentials, options)
    510 
    511 /*
    512 
    513 Lookup slice detail for slices matching ‘match’ options.
    514 
    515 ‘filter’ options indicate what detail to provide. See generic lookup_* method description above.
    516 
    517 '''Arguments:'''
    518 options: What details to provide (filter options) for which slices (match options)
    519 
    520 '''Return:''' List of dictionaries with field/value pairs for each returned slice
    521 
    522 */
    523 
    524 function '''lookup_slices''' (credentials, options)
    525 
    526 /*
    527 
    528 Update fields in given slice object. See generic update_* method description above.
    529 
    530 '''Arguments:'''
    531 
    532 slice_urn: URN of slice to update
    533 
    534 Options: Contains ‘fields’ key referring dictionary of name/value pairs to update
    535 
    536 '''Return:''' None
    537 
    538 */
    539 
    540 function '''update_slice'''(slice_urn, credentials, options)
    541 
    542 /*
    543 
    544 Provide list of credentials for the invoking member relative to the given slice. If the invocation is in a speaks-for context, the credentials will be for the ‘spoken-for’ member, not the invoking tool.
    545 
    546 For example, this call may return a standard SFA Slice Credential and some ABAC credentials indicating the role of the member with respect to the slice.
    547 
    548 Note: When creating an SFA-style Slice Credential, the following roles typically allow users to operate at known GENI-compatible aggregates: "*" (asterisk) or the list of "refresh", "embed", "bind", "control" "info".
    549 
    550 '''Arguments:'''
    551 
    552 slice_urn: URN of slice for which to get member’s credentials
    553 
    554 options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
    555 
    556 '''Return:'''
    557 
    558 List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
    559 
    560 */
    561 
    562 function '''get_credentials'''(slice_urn, credentials, options)
     478{{{
     479#!python
     480# Provide details on the version, services and options supported by this SA
     481#
     482# Arguments:
     483#    Options:
     484#
     485# Return:
     486#   get_version structure information as described above
     487def get_version()
     488}}}
     489
     490{{{
     491#!python
     492# Create a new slice, optionally within a project. See generic create_* method description above.
     493#
     494# Arguments:
     495#
     496#   Options:
     497#       'fields', a dictionary field/value pairs for object to be created
     498#
     499# Return:
     500#   Dictionary of field/value pairs for created slice (e.g. slice URN, slice UUID, expiration and slice credential)
     501#
     502# Should return DUPLICATE_ERROR if creating a slice for which a non-expired slice of same name exists.
     503def create_slice (credentials, options)
     504}}}
     505
     506{{{
     507#!python
     508# Lookup slice detail for slices matching ‘match’ options.
     509#
     510# ‘filter’ options indicate what detail to provide. See generic lookup_* method description above.
     511#
     512# Arguments:
     513#    options: What details to provide (filter options) for which slices (match options)
     514#
     515# Return: List of dictionaries with field/value pairs for each returned slice
     516#
     517def lookup_slices (credentials, options)
     518}}}
     519
     520{{{
     521#!python
     522# Update fields in given slice object. See generic update_* method description above.
     523#
     524# Arguments:
     525#   slice_urn: URN of slice to update
     526#
     527#    Options: Contains ‘fields’ key referring dictionary of name/value pairs to update
     528# Return: None
     529#
     530def update_slice(slice_urn, credentials, options)
     531}}}
     532
     533{{{
     534#!python
     535# Provide list of credentials for the invoking member relative to the given slice. If the invocation is in a speaks-for context, the credentials will be for the ‘spoken-for’ member, not the invoking tool.
     536#
     537# For example, this call may return a standard SFA Slice Credential and some ABAC credentials indicating the role of the member with respect to the slice.
     538#
     539# Note: When creating an SFA-style Slice Credential, the following roles typically allow users to operate at known GENI-compatible aggregates: "*" (asterisk) or the list of "refresh", "embed", "bind", "control" "info".
     540#
     541# Arguments:
     542#   slice_urn: URN of slice for which to get member’s credentials
     543#   options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
     544# Return:
     545#   List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
     546def get_credentials(slice_urn, credentials, options)
     547}}}
    563548
    564549== Slice Member Service Methods ==
     
    568553The 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.
    569554
    570 /*
    571 
    572 Modify slice membership, adding, removing and changing roles of members with respect to given slice
    573 
    574 '''Arguments:'''
    575 
    576 Slice_urn: URN of slice for which to modify membership
    577 
    578 '''Options:'''
    579 
    580 members_to_add: List of member_urn/role tuples for members to add to slice of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
    581 
    582 members_to_remove: List of member_urn of members to remove from slice
    583 
    584 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}
    585 
    586 '''Return:'''
    587 
    588 None
    589 
    590 */
    591 
    592 function '''modify_slice_membership''' (slice_urn, credentials, options)
    593 
    594 /*
    595 
    596 Lookup members of given slice and their roles within that slice
    597 
    598 '''Arguments:'''
    599 
    600 slice_urn: URN of slice for which to provide current members and roles
    601 
    602 '''Return:'''
    603 
    604 List of dictionaries of member_urn/role pairs [{‘SLICE_MEMBER’: member_urn, ‘SLICE_ROLE’: role }...] where ‘role’ is a string of the role name
    605 
    606 */
    607 
    608 function '''lookup_slice_members''' (slice_urn, credentials, options)
    609 
    610 /*
    611 
    612 Lookup slices for which the given member belongs
    613 
    614 '''Arguments:'''
    615 
    616 Member_urn: The member for whom to find slices to which it belongs
    617 
    618 '''Return:'''
    619 
    620 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
    621 
    622 */
    623 
    624 function '''lookup_slices_for_member'''(member_urn, credentials, options)
     555{{{
     556#!python
     557# Modify slice membership, adding, removing and changing roles of members with respect to given slice
     558#
     559# Arguments:
     560#   Slice_urn: URN of slice for which to modify membership
     561#   Options:
     562#       members_to_add: List of member_urn/role tuples for members to add to slice of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
     563#       members_to_remove: List of member_urn of members to remove from slice
     564#       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}
     565#
     566# Return:
     567#   None
     568def modify_slice_membership(slice_urn, credentials, options)
     569}}}
     570
     571{{{
     572#!python
     573# Lookup members of given slice and their roles within that slice
     574#
     575# Arguments:
     576#   slice_urn: URN of slice for which to provide current members and roles
     577#
     578# Return:
     579#    List of dictionaries of member_urn/role pairs [{‘SLICE_MEMBER’: member_urn, ‘SLICE_ROLE’: role }...] where ‘role’ is a string of the role name
     580def 'lookup_slice_members(slice_urn, credentials, options)
     581}}}
     582
     583{{{
     584#!python
     585# Lookup slices for which the given member belongs
     586#
     587# Arguments:
     588#   Member_urn: The member for whom to find slices to which it belongs
     589#
     590# Return:
     591#    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
     592def lookup_slices_for_member(member_urn, credentials, options)
     593}}}
    625594
    626595== Sliver Info Service Methods ==
     
    640609|| SLIVER_INFO_CREATION || DATETIME || Time of sliver creation || No || Allowed || No ||
    641610
    642 /*
    643 
    644 Create a record of a sliver creation
    645 
    646 '''Arguments:'''
    647 
    648 options: 'fields' containing the fields for the sliver info  being registered at SA
    649 
    650 '''Return:'''
    651 
    652 Dictionary of name/value pairs for created sliver_info record
    653 
    654 */
    655 
    656 function '''create_sliver_info'''(credentials, options)
    657 
    658 /*
    659 
    660 Delete a sliver_info record
    661 
    662 '''Arguments:'''
    663 
    664 sliver_urn: urn of sliver whose record is to be deleted
    665 
    666 '''Return:'''
    667 
    668 True if succeeded
    669 
    670 Should return ARGUMENT_ERROR if no such sliver urn is registered
    671 
    672 */
    673 
    674 function '''delete_sliver_info'''(sliver_urn, credentials, options)
    675 
    676 /*
    677 
    678 Update the details of a sliver_info record
    679 
    680 '''Arguments:'''
    681 
    682 sliver_urn: urn of sliver for which to update
    683 
    684 options: 'fields' containing fields for sliver_infos that are permitted for update
    685 
    686 '''Return:'''
    687 
    688 True if succeeded
    689 
    690 Should return ARGUMENT_ERROR if no such sliver_urn is found
    691 
    692 */
    693 
    694 function '''update_sliver_info'''(sliver_urn, credentials, options)
    695 
    696 /*
    697 
    698 Lookup sliver_info for given match criteria return fields in given filter criteria
    699 
    700 '''Arguments:'''
    701 
    702 options: 'match' for query match criteria, 'filter' for fields to be returned
    703 
    704 '''Return:'''
    705 
    706 Dictionary (indexed by sliver_urn) of dictionaries containing name/value pairs for all sliver_infos registered at this SA matching given criteria.
    707 
    708 */
    709 
    710 function '''lookup_sliver_info'''(credentials, options)
    711 
     611{{{
     612#!python
     613# Create a record of a sliver creation
     614#
     615# Arguments:
     616#   options: 'fields' containing the fields for the sliver info  being registered at SA
     617#
     618# Return:
     619# Dictionary of name/value pairs for created sliver_info record
     620def create_sliver_info(credentials, options)
     621}}}
     622
     623{{{
     624#!python
     625# Delete a sliver_info record
     626#
     627# Arguments:
     628#    sliver_urn: urn of sliver whose record is to be deleted
     629#
     630# Return:
     631#   True if succeeded
     632#
     633#Should return ARGUMENT_ERROR if no such sliver urn is registered
     634def delete_sliver_info(sliver_urn, credentials, options)
     635}}}
     636
     637{{{
     638#!python
     639# Update the details of a sliver_info record
     640#
     641#Arguments:
     642#   sliver_urn: urn of sliver for which to update
     643#   options: 'fields' containing fields for sliver_infos that are permitted for update
     644#
     645# Return:
     646#   True if succeeded
     647#
     648# Should return ARGUMENT_ERROR if no such sliver_urn is found
     649def update_sliver_info(sliver_urn, credentials, options)
     650}}}
     651
     652{{{
     653#!python
     654# Lookup sliver_info for given match criteria return fields in given filter criteria
     655#
     656# Arguments:
     657#   options: 'match' for query match criteria, 'filter' for fields to be returned
     658#
     659# Return:
     660#    Dictionary (indexed by sliver_urn) of dictionaries containing name/value pairs for all sliver_infos registered at this SA matching given criteria.
     661def lookup_sliver_info(credentials, options)
     662}}}
    712663
    713664== Project Service Methods ==
     
    726677|| PROJECT_DESCRIPTION || STRING || Description of Project || No || Allowed || Yes ||
    727678
    728 /*
    729 
    730 Create project with given details. See generic create_* description above.
    731 
    732 '''Arguments:'''
    733 
    734 Options: 'fields', a dictionary of name/value pairs for newly created project.
    735 
    736 '''Return:'''
    737 
    738 Dictionary of name/value pairs of newly created project including urn
    739 
    740 Should return DUPLICATE_ERROR if creating a project for which a project of same name exists.
    741 
    742 */
    743 
    744 function '''create_project'''(credentials, options)
    745 
    746 /*
    747 
    748 Lookup project detail for projects matching ‘match options.
    749 
    750 ‘filter options indicate what detail to provide.
    751 
    752 '''Arguments:'''
    753 
    754 options: What details to provide (filter options) for which members (match options)
    755 
    756 '''Return:''' Dictionary of name/value pairs from ‘filter’ options for each project matching ‘match’ option criteria.
    757 
    758 */
    759 
    760 function '''lookup_projects''' (credentials, options)
    761 
    762 /*
    763 
    764 Update fields in given project object, as allowed in Get_version advertisement. See generic update_* description above.
    765 
    766 '''Arguments:'''
    767 
    768 project_urn: URN of project to update
    769 
    770 Options: Contains ‘fields’ key referencing dictionary of key/value pairs to update project
    771 '''
    772 Return:''' None
    773 
    774 */
    775 
    776 function '''update_project'''(project_urn, credentials, options)
     679{{{
     680#!python
     681# Create project with given details. See generic create_* description above.
     682#
     683# Arguments:
     684#   Options: 'fields', a dictionary of name/value pairs for newly created project.
     685#
     686# Return:
     687#   Dictionary of name/value pairs of newly created project including urn
     688#
     689#Should return DUPLICATE_ERROR if creating a project for which a project of same name exists.
     690def create_project(credentials, options)
     691}}}
     692
     693{{{
     694#!python
     695# Lookup project detail for projects matching ‘match options.
     696# ‘filter options indicate what detail to provide.
     697#
     698# Arguments:
     699#    options: What details to provide (filter options) for which members (match options)
     700#
     701# Return:
     702#    Dictionary of name/value pairs from ‘filter’ options for each project matching ‘match’ option criteria.
     703def lookup_projects(credentials, options)
     704}}}
     705
     706{{{
     707#!python
     708# Update fields in given project object, as allowed in Get_version advertisement. See generic update_* description above.
     709#
     710# Arguments:
     711#    project_urn: URN of project to update
     712#    Options: Contains ‘fields’ key referencing dictionary of key/value pairs to update project
     713#
     714# Return: None
     715def update_project(project_urn, credentials, options)
     716}}}
    777717
    778718== Project Member Service Methods ==
     
    780720Projects may have members associated with them in particular roles. See the Slice Member Service Methods above for more description.
    781721
    782 /*
    783 
    784 Modify project membership, adding, removing and changing roles of members with respect to given project
    785 '''
    786 Arguments:'''
    787 
    788 project_urn: Name of project for which to modify membership
    789 
    790 '''Options:'''
    791 
    792 members_to_add: List of member_urn/role tuples for members to add to project of form {‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’ : role}
    793 
    794 members_to_remove: List of member_urn of members to remove from project
    795 
    796 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}
    797 '''
    798 Return:'''
    799 
    800 None
    801 
    802 */
    803 
    804 function '''modify_project_membership''' (project_urn, credentials, options)
    805 
    806 /*
    807 
    808 Lookup members of given project and their roles within that project
    809 
    810 '''Arguments:'''
    811 
    812 project_urn: project_urn for which to provide current members and roles
    813 
    814 '''Return:'''
    815 
    816 List of dictionaries of member_urn/role pairs of form [{‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’: role}...]
    817 
    818 */
    819 
    820 function '''lookup_project_members''' (project_urn, credentials, options)
    821 
    822 /*
    823 
    824 Lookup projects for which the given member belongs
    825 
    826 '''Arguments:'''
    827 
    828 Member_urn: The member for whom to find project to which it belongs
    829 
    830 '''Return:'''
    831 
    832 Dictionary of slice_urn/role pairs (‘PROJECT_URN’ : project_urn, ‘PROJECT_ROLE’ : role} where role is a string of the role name
    833 
    834 */
    835 
    836 function '''lookup_projects_for_member'''(member_urn, credentials, options)
     722{{{
     723#!python
     724# Modify project membership, adding, removing and changing roles of members with respect to given project
     725#
     726# Arguments:
     727#   project_urn: Name of project for which to modify membership
     728#   Options:
     729#      members_to_add: List of member_urn/role tuples for members to add to project of form {‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’ : role}
     730#      members_to_remove: List of member_urn of members to remove from project
     731#      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}
     732#
     733# Return:  None
     734def modify_project_membership(project_urn, credentials, options)
     735}}}
     736
     737{{{
     738#!python
     739# Lookup members of given project and their roles within that project
     740#
     741# Arguments:
     742#    project_urn: project_urn for which to provide current members and roles
     743#
     744#Return:
     745#   List of dictionaries of member_urn/role pairs of form [{‘PROJECT_MEMBER’: member_urn, ‘PROJECT_ROLE’: role}...]
     746def lookup_project_members (project_urn, credentials, options)
     747}}}
     748
     749{{{
     750#!python
     751# Lookup projects for which the given member belongs
     752#
     753# Arguments:
     754#    Member_urn: The member for whom to find project to which it belongs
     755#
     756# Return:
     757#    Dictionary of slice_urn/role pairs (‘PROJECT_URN’ : project_urn, ‘PROJECT_ROLE’ : role} where role is a string of the role name
     758def lookup_projects_for_member(member_urn, credentials, options)
     759}}}
    837760
    838761== Member Authority API ==
     
    876799|| MEMBER_EMAIL || STRING || Email of user || No || Identifying ||
    877800
    878 /*
    879 
    880 Return information about version and options (filter, query, credential types) accepted by this member authority
    881 
    882 '''Arguments:'''
    883 
    884 None
    885 
    886 '''Return:'''
    887 
    888 get_version structure information as described above
    889 
    890 */
    891 
    892 function '''get_version'''()
    893 
    894 /*
    895 Lookup public information about members matching given criteria
    896 
    897 '''Arguments:'''
    898 
    899 options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return
    900 
    901 '''Return:'''
    902 
    903 Dictionary indexed by member URN of dictionaries of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria
    904 
    905 */
    906 
    907 function '''lookup_public_member_info''' (options)
    908 
    909 /*
    910 
    911 Lookup private (SSL/SSH key) information about members matching given criteria
    912 
    913 '''Arguments:'''
    914 
    915 options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return
    916 
    917 '''Return:'''
    918 
    919 Dictionary indexed by member URN of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria
    920 
    921 */
    922 
    923 function '''lookup_private_member_info''' (credentials, options)
    924 
    925 /*
    926 
    927 Lookup identifying (e.g. name, email) info about matching members
    928 
    929 '''Arguments:'''
    930 
    931 options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return
    932 
    933 '''Return:'''
    934 
    935 Dictionary indexed by member URN of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria
    936 
    937 */
    938 
    939 function '''lookup_identifying_member_info''' (credentials, options)
    940 
    941 /*
    942 
    943 Update information about given member public, private or identifying information
    944 
    945 '''Arguments:'''
    946 
    947 member_urn: URN of member for whom to set information
    948 
    949 options: Containing ‘update’ key with dictionary of name/value pairs to update info for given member
    950 
    951 '''Return:'''
    952 
    953 None
    954 
    955 */
    956 
    957 function '''update_member_info''' (member_urn, credentials, options)
    958 
    959 /*
    960 
    961 Provide list of credentials (signed statements) for given member
    962 This is member-specific information suitable for passing as credentials in an AM API call for aggregate authorization.
    963 
    964 '''Arguments:'''
    965 
    966 member_urn: URN of member for which to retrieve credentials
    967 
    968 options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
    969 
    970 '''Return:'''
    971 
    972 List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
    973 
    974 */
    975 
    976 function '''get_credentials'''(member_urn, credentials, options)
     801{{{
     802#!python
     803# Return information about version and options (filter, query, credential types) accepted by this member authority
     804#
     805# Arguments: None
     806#
     807# Return:
     808#     get_version structure information as described above
     809def get_version()
     810}}}
     811
     812{{{
     813#!python
     814# Lookup public information about members matching given criteria
     815#
     816# Arguments:
     817#   options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return
     818#
     819# Return:
     820#   Dictionary indexed by member URN of dictionaries of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria
     821def lookup_public_member_info (options)
     822}}}
     823
     824{{{
     825#!python
     826# Lookup private (SSL/SSH key) information about members matching given criteria
     827#
     828# Arguments:
     829#    options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return
     830#
     831# Return:
     832#    Dictionary indexed by member URN of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria
     833def lookup_private_member_info (credentials, options)
     834}}}
     835
     836{{{
     837#!python
     838# Lookup identifying (e.g. name, email) info about matching members
     839#
     840# Arguments:
     841#    options: set of ‘filter’ and ‘match’ criteria specifying which members and which fields for each member to return
     842#
     843# Return:
     844#    Dictionary indexed by member URN of name/value pairs of fields specified in ‘filter’ options for members matching ‘match’ criteria
     845def  lookup_identifying_member_info(credentials, options)
     846}}}
     847
     848{{{
     849#!python
     850# Update information about given member public, private or identifying information
     851#
     852# Arguments:
     853#    member_urn: URN of member for whom to set information
     854#    options: Containing ‘update’ key with dictionary of name/value pairs to update info for given member
     855#
     856# Return: None
     857def update_member_info(member_urn, credentials, options)
     858}}}
     859
     860{{{
     861#!python
     862# Provide list of credentials (signed statements) for given member
     863# This is member-specific information suitable for passing as credentials in an AM API call for aggregate authorization.
     864# Arguments:
     865#    member_urn: URN of member for which to retrieve credentials
     866#    options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
     867#
     868# Return:
     869#     List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
     870def get_credentials(member_urn, credentials, options)
     871}}}
    977872
    978873== Key Service Methods ==
     
    991886Note that access to key information is subject to authorization policy. The public keys are likely to be readily available but access to the private keys will be tightly restricted (often only to the user or authorized proxy). Requests to lookup information for which the requestor is not authorized should fail on, at least, a per row basis. That is, if one asks for KEY_PUBLIC and KEY_PRIVATE for a list of member_urn's, the key pair should be returned only for those members to whom access to BOTH halves of the key are allowed. Note also that storing the private key is optional: an empty private key returned from a lookup method is an indication that no such key is stored, not that the access to the private key is not authorized.
    992887
    993 /*
    994 
    995 Create a record for a key pair for given member
    996 
    997 '''Arguments:'''
    998 
    999 member_urn: URN of member for which to retrieve credentials
    1000 
    1001 options: 'fields' containing the fields for the key pair being stored
    1002 
    1003 '''Return:'''
    1004 
    1005 Dictionary of name/value pairs for created key record including the KEY_ID
    1006 
    1007 Should return DUPLICATE_ERROR if a key with the same KEY_ID is already stored for given user
    1008 
    1009 */
    1010 
    1011 function '''create_key'''(member_urn, credentials, options)
    1012 
    1013 /*
    1014 
    1015 Delete a key pair for given member
    1016 
    1017 '''Arguments:'''
    1018 
    1019 member_urn: urn of member for which to delete key pair
    1020 
    1021 key_id: KEY_ID (fingerprint) of key pair to be deleted
    1022 
    1023 '''Return:'''
    1024 
    1025 True if succeeded
    1026 
    1027 Should return ARGUMENT_ERROR if no such key is found for user
    1028 
    1029 */
    1030 
    1031 function '''delete_key'''(member_urn, key_id, credentials, options)
    1032 
    1033 /*
    1034 
    1035 Update the details of a key pair for given member
    1036 
    1037 '''Arguments:'''
    1038 
    1039 member_urn: urn of member for which to delete key pair
    1040 
    1041 key_id: KEY_ID (fingerprint) of key pair to be deleted
    1042 
    1043 options: 'fields' containing fields for key pairs that are permitted for update
    1044 
    1045 '''Return:'''
    1046 
    1047 True if succeeded
    1048 
    1049 Should return ARGUMENT_ERROR if no such key is found for user
    1050 
    1051 */
    1052 
    1053 function '''update_key'''(member_urn, key_id, credentials, options)
    1054 
    1055 /*
    1056 
    1057 Lookup keys for given match criteria return fields in given filter criteria
    1058 
    1059 '''Arguments:'''
    1060 
    1061 options: 'match' for query match criteria, 'filter' for fields to be returned
    1062 
    1063 '''Return:'''
    1064 
    1065 Dictionary (indexed by member_urn) of dictionaries containing name/value pairs for all keys registered for that given user.
    1066 
    1067 */
    1068 
    1069 function '''lookup_keys'''(credentials, options)
     888{{{
     889#!python
     890# Create a record for a key pair for given member
     891#
     892# Arguments:
     893#    member_urn: URN of member for which to retrieve credentials
     894#    options: 'fields' containing the fields for the key pair being stored
     895#
     896# Return:
     897#    Dictionary of name/value pairs for created key record including the KEY_ID
     898#
     899# Should return DUPLICATE_ERROR if a key with the same KEY_ID is already stored for given user
     900def create_key(member_urn, credentials, options)
     901}}}
     902
     903{{{
     904#!python
     905# Delete a key pair for given member
     906#
     907# Arguments:
     908#    member_urn: urn of member for which to delete key pair
     909#    key_id: KEY_ID (fingerprint) of key pair to be deleted
     910#
     911# Return:
     912#    True if succeeded
     913#
     914# Should return ARGUMENT_ERROR if no such key is found for user
     915def delete_key(member_urn, key_id, credentials, options)
     916}}}
     917
     918{{{
     919#!python
     920# Update the details of a key pair for given member
     921#
     922# Arguments:
     923#    member_urn: urn of member for which to delete key pair
     924#    key_id: KEY_ID (fingerprint) of key pair to be deleted
     925#    options: 'fields' containing fields for key pairs that are permitted for update
     926#
     927# Return:
     928#    True if succeeded
     929#
     930# Should return ARGUMENT_ERROR if no such key is found for user
     931def update_key(member_urn, key_id, credentials, options)
     932}}}
     933
     934{{{
     935#!python
     936# Lookup keys for given match criteria return fields in given filter criteria
     937#
     938# Arguments:
     939#    options: 'match' for query match criteria, 'filter' for fields to be returned
     940#
     941# Return:
     942#    Dictionary (indexed by member_urn) of dictionaries containing name/value pairs for all keys registered for that given user.
     943def lookup_keys(credentials, options)
     944}}}
    1070945
    1071946== Appendix: Federation Object Models ==