Changes between Version 17 and Version 18 of UniformClearinghouseAPIV2


Ignore:
Timestamp:
11/13/13 08:18:39 (6 years ago)
Author:
mbrinn@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPIV2

    v17 v18  
    6464# Arguments:
    6565#  argl : ...
    66 #  credentials : list of {type : credential} tuples representing credentials provided by caller to support AuthZ on method call.
     66#  credentials : list of {type : credential} tuples representing credentials
     67#     provided by caller to support AuthZ on method call.
    6768#      [NB: This argument will be omitted in descriptions below. ]
    6869#  options : … [ Recognized options: ….]
    6970#
    7071# Return:
    71 #  E.g. a list of dictionaries with these fields mandatory (…) and these fields optional (…)
     72#  E.g. a list of dictionaries with these fields mandatory (…)
     73#                                         and these fields optional (…)
    7274def fed_func (arg1, arg2, credentials, options)
    7375}}}
     
    9395     * “PROTECT” attributes may be labeled as “PUBLIC”, “PRIVATE” or “IDENTIFYING”. These are for the Member Authority Only to differentiate between public, identifying and private data fields on members. The default, if not provided, is "PUBLIC", and thus this attribute is optional.
    9496
    95 The FIELDS element of the get_version should contain all supplementary (non-mandatory) field objects supported by a given service. Additionally, it should contain mandatory field objects for which the default semantics (for "CREATE", "MATCH", "UPDATE", "PROTECT") should be overridden. The FIELDS element is thus optional for all services.
     97The FIELDS element of the get_version should contain all supplementary (non-mandatory) field objects supported by a given service. Additionally, it may contain mandatory field objects for which the default semantics (for "CREATE", "MATCH", "UPDATE", "PROTECT") should be overridden. The FIELDS element is thus optional for all services.
    9698
    9799Supplementary field names should be placed in a distinct namespace by a prefix unique to that federation, and starting with an underscore (e.g _GENI_,  _OFELIA_ , _FED4FIRE_ or _PROTOGENI_ etc.).
     
    102104{{{
    103105#!python
    104 # Return information about version and options (filter, query, credential types) accepted by this service
     106# Return information about version and options
     107#   (e.g. filter, query, credential types) accepted by this service
    105108#
    106109# Arguments: None
     
    212215{{{
    213216#!python
    214 # Creates a new instance of the given object with a ‘fields’ option specifying particular field values that are to be associated with the object.
    215 # These may only include those fields specified as ‘ALLOWED or ‘REQUIRED’ in the ‘Creation’ column of the object descriptions below
    216 # or in the “CREATE’ key in the supplemental fields in the get_version specification for that object.
    217 # If successful, the call returns a dictionary of the fields associated with the newly created object.
     217# Creates a new instance of the given object with a ‘fields’ option
     218# specifying particular field values that are to be associated with the object.
     219# These may only include those fields specified as ‘ALLOWED or ‘REQUIRED’
     220# in the ‘Creation’ column of the object descriptions below
     221# or in the “CREATE’ key in the supplemental fields in the
     222# get_version specification for that object.
     223# If successful, the call returns a dictionary of the fields
     224# associated with the newly created object.
    218225#
    219226#
     
    225232#
    226233# Return:
    227 #   Dictionary of field/value pairs for created slice (e.g. slice URN, slice UUID, expiration and slice credential)
    228 #
    229 # Should return DUPLICATE_ERROR if creating a slice for which a non-expired slice of same name exists.
     234#   Dictionary of field/value pairs for created slice
     235#     (e.g. slice URN, slice UUID, expiration and slice credential)
     236#
     237# Should return DUPLICATE_ERROR if creating a slice for
     238#   which a non-expired slice of same name exists.
    230239def create(type, credentials, options)
    231240}}}
     
    233242{{{
    234243#!python
    235 # Updates an object instance specified by URN with a ‘fields’ option specifying the particular fields to update.
    236 # Only a single object can be updated from a single update call. The fields may include those specified as ‘Yes’ in the ‘Update’ column
    237 # of the object descriptions below, or ’TRUE’ in the ‘UPDATE’ key in the supplemental fields provided by the get_version call.
    238 # Note: There may be more than one entity of a given URN at an authority, but only one ‘live’ one (any other is archived and cannot be updated).
     244# Updates an object instance specified by URN with a ‘fields’ option
     245#  specifying the particular fields to update.
     246# Only a single object can be updated from a single update call.
     247# The fields may include those specified as ‘Yes’ in the ‘Update’ column
     248# of the object descriptions below, or ’TRUE’ in the ‘UPDATE’ key in the
     249# supplemental fields provided by the get_version call.
     250# Note: There may be more than one entity of a given URN at an authority,
     251# but only one ‘live’ one (any other is archived and cannot be updated).
    239252#
    240253# Arguments:
    241254#   type: type of object to be updated
    242255#   urn: URN of object to update
    243 #
    244 #    Options: Contains ‘fields’ key referring dictionary of name/value pairs to update
     256#   options: Contains ‘fields’ key referring dictionary of name/value pairs to update
     257#
    245258# Return: None
    246259#
     
    266279#!python
    267280# Lookup requested details for objects matching ‘match’ options.
    268 # This call takes a set of ‘match’ criteria provided in the ‘options’ field, and returns a dictionary of dictionaries of object attributes keyed by object URN matching these criteria.
     281# This call takes a set of ‘match’ criteria provided in the ‘options’ field,
     282# and returns a dictionary of dictionaries of object attributes keyed by object URN matching these criteria.
    269283# If a ‘filter’ option is provided, only those attributes listed in the ‘filter’ options are returned.
    270284# The requirements on match criteria supported by a given service are service-specific;
    271 # however it is recommended that policies restrict lookup calls to requests that are bounded to particular sets of explicitly listed objects (and not open-ended queries).
     285# however it is recommended that policies restrict lookup calls to requests that are bounded
     286# to particular sets of explicitly listed objects (and not open-ended queries).
     287#
     288# See additional details on the lookup method in the document section below.
    272289#
    273290#
    274291# Arguments:
    275292#    type: type of objects for which details are being requested
    276 #    options: What details to provide (filter options) for which slices (match options)
    277 #
    278 # Return: List of dictionaries (indexed by object URN) with field/value pairs for each returned object
     293#    options: What details to provide (filter options)
     294#            for which objects (match options)
     295#
     296# Return: List of dictionaries (indexed by object URN) with field/value pairs
     297#   for each returned object
    279298#
    280299def lookup (type, credentials, options)
     
    434453    {
    435454       …
    436        "TYPES" : ["SLICE_AUTHORITY", "MEMBER_AUTHORITY", "AGGREGATE_MANAGER", ...]
     455       "TYPES" : ["SLICE_AUTHORITY", "MEMBER_AUTHORITY",
     456                      "AGGREGATE_MANAGER", ...]
    437457       …
    438458    }
    439459}}}
    440460
    441 This table contains a set of example services types (of which only SLICE_AUTHORITY, MEMBER_AUTHORITY and AGGREGATE_MANAGER are required for any given federation):
     461This table contains a set of ''example'' services types (of which only SLICE_AUTHORITY, MEMBER_AUTHORITY and AGGREGATE_MANAGER are required for any given federation):
    442462
    443463|| ''' Service ''' || ''' Description ''' ||
     
    445465|| MEMBER_AUTHORITY || An instance of the Member Authority Federation service described in this document ||
    446466|| AGGREGATE_MANAGER || An instance of an Aggregate Manager satisfying the Aggregate Manager API ||
    447 || STITCHING_COMPUTATION_SERVICE || A toplogy service for supporting cross-aggregate stitching ||
     467|| STITCHING_COMPUTATION_SERVICE || A topology service for supporting cross-aggregate stitching ||
    448468|| CREDENTIAL_STORE || A service holding credentials for the federation, typically for supporting federation authentication services ||
    449469|| LOGGING_SERVICE || A service to support federation-level event logging ||
     
    459479|| SERVICE_NAME || String || Short name of service || Yes || No ||
    460480|| SERVICE_DESCRIPTION || String || Descriptive name of service || No || No ||
    461 || SERVICE_PEERS || URLs and version info for other running version of same service (see below) || No || No ||
    462 
    463 The SERVICE_PEERS field is similar to that in the AM API: a list of {version", 'url'} dictionaries for other supported peer services. An example would be as follows:
     481|| SERVICE_PEERS || List of Dictionaries || URLs and version info for other running version of same service (see below) || No || No ||
     482
     483The SERVICE_PEERS field is similar to that in the AM API: a list of {version", 'url'} dictionaries for other supported peer services of different versions. An example would be as follows:
    464484{{{
    465485[
     
    470490}}}
    471491
    472 {{{
    473 #!python
    474 # Provide a structure detailing the version information as well as details of accepted options for Registry API calls.
    475 #
    476 # Arguments:
    477 #   None
    478 #
    479 # Return:
    480 #   get_version structure information as described above
    481 def get_version()
    482 }}}
    483 
    484 {{{
    485 #!python
    486 # Return information about all aggregates associated with the Federation
    487 #
    488 # Arguments:
    489 #  options: 'match' and 'filter' options   as described in standard lookup methods
    490 #
    491 # Return:
    492  #  dictionary indexed by service URN of name/value pairs for each returned service
    493 def lookup(options)
    494 }}}
    495 
     492The Registry API supports these standard API methods for type="SERVICE", with elaboration in the following table:
     493
     494|| ''' Method ''' || ''' Description ''' ||
     495|| lookup || lookup services matching given match criteria. ||
     496
     497Additionally, the Registry API supports the following methods:
    496498
    497499The following method maps object URN's to authority URN's. Note that the transformation from the URN's of objects (e.g. slice, project, member) to the URN's of their authority is a simple one, for example:
     
    569571|| SLICE_PROJECT_URN || URN || URN of project to which slice is associated (if SA supports project) || Yes || Required (if SA supports project) || No ||
    570572
    571 To clarify the semantics of the SLICE_PROJECT_URN field, it is a required field for those SAs that support the PROJECT service (and in this context may be matched and is required at creation time, but not updatable). In SAs that do not support projects, the field is not meaningful and should not be supported.
     573To clarify the semantics of the SLICE_PROJECT_URN field: it is a required field for those SAs that support the PROJECT service (and in this context may be matched and is required at creation time, but not updatable). In SAs that do not support projects, the field is not meaningful and should not be supported.
    572574
    573575NB: 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.
     
    578580|| create || Creates a  new slice with provided details  ||
    579581|| 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|| ~~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.  ||
     583|| lookup || lookup slices matching given match criteria subject to authorization restrictions. ||
    582584
    583585Additionally, the Slice service provides the following methods:
     
    585587{{{
    586588#!python
    587 # 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.
    588 #
    589 # 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.
    590 #
    591 # 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".
     589# Provide list of credentials for the invoking member relative to the given slice.
     590# If the invocation is in a speaks-for context, the credentials will be for the
     591# ‘spoken-for’ member, not the invoking tool.
     592#
     593# For example, this call may return a standard SFA Slice Credential and some
     594# ABAC credentials indicating the role of the member with respect to the slice.
     595#
     596# Note: When creating an SFA-style Slice Credential, the following roles typically
     597# allow users to operate at known GENI-compatible aggregates: "*" (asterisk)
     598# or the list of "refresh", "embed", "bind", "control" "info".
    592599#
    593600# Arguments:
    594601#   slice_urn: URN of slice for which to get member’s credentials
    595 #   options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
     602#   options: Potentially contains ‘speaking-for’ key indicating a speaks-for
     603# invocation (with certificate of the accountable member in the credentials argument)
    596604# Return:
    597 #   List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
     605#   List of credential in “CREDENTIALS” format, i.e. a list of credentials with
     606# type information suitable for passing to aggregates speaking AM API V3.
    598607def get_credentials(slice_urn, credentials, options)
    599608}}}
     
    609618{{{
    610619#!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")
     620# Modify object membership, adding, removing and changing roles of members
     621#    with respect to given object
     622#
     623# Arguments:
     624#   type: type of object for whom to lookup membership (in the case of
     625#       Slice Member Service, "SLICE", in the case of Project Member Service, "PROJECT")
    615626#   urn: URN of slice/project for which to modify membership
    616627#   Options:
    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)
     628#       members_to_add: List of member_urn/role tuples for members to add to
     629#              slice/project of form {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
     630#                    (or 'PROJECT_MEMBER/PROJECT_ROLE for Project Member Service)
    618631#       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)
     632#       members_to_change: List of member_urn/role tuples for members whose role
     633#                should change as specified for given slice/project of form
     634#                {‘SLICE_MEMBER’ : member_urn, ‘SLICE_ROLE’ : role}
     635#                (or 'PROJECT_MEMBER/PROJECT_ROLE for Project Member Service)
    620636#
    621637# Return:
     
    629645#
    630646# 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")
     647#   type: type of object for whom to lookup membership
     648#          (in the case of Slice Member Service, "SLICE",
     649#           in the case of Project Member Service, "PROJECT")
    632650#   urn: URN of object for which to provide current members and roles
    633651#
    634652# 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.
     653#    List of dictionaries of member_urn/role pairs
     654#       [{‘SLICE_MEMBER’: member_urn, ‘SLICE_ROLE’: role }...]
     655#         (or PROJECT_MEMBER/PROJECT_ROLE for Project Member Service)
     656#          where ‘role’ is a string of the role name.
    636657def lookup_members(type, urn, credentials, options)
    637658}}}
     
    645666#
    646667# Return:
    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
     668#    List of dictionary of urn/role pairs [(‘SLICE_URN’ : slice_urn, ‘SLICE_ROLE’ : role} ...]
     669#        (or PROJECT_MEMBER/PROJECT_ROLE for Project Member Service)
     670#       for each object to which a member belongs, where role is a string of the role name
    648671def lookup_for_member(type, member_urn, credentials, options)
    649672}}}
     
    764787#!python
    765788# Provide list of credentials (signed statements) for given member
    766 # This is member-specific information suitable for passing as credentials in an AM API call for aggregate authorization.
     789# This is member-specific information suitable for passing as credentials in
     790#  an AM API call for aggregate authorization.
    767791# Arguments:
    768792#    member_urn: URN of member for which to retrieve credentials
    769 #    options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
     793#    options: Potentially contains ‘speaking-for’ key indicating a speaks-for
     794#        invocation (with certificate of the accountable member in the credentials argument)
    770795#
    771796# Return:
    772 #     List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
     797#     List of credential in “CREDENTIALS” format, i.e. a list of credentials with
     798#        type information suitable for passing to aggregates speaking AM API V3.
    773799def get_credentials(member_urn, credentials, options)
    774800}}}