Context Navigation

Changes between Version 17 and Version 18 of UniformClearinghouseAPIV2

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

Legend:

: Unmodified
: Added
: Removed
: Modified

UniformClearinghouseAPIV2

-                      v17
+                      v18
 # Arguments:
 #  argl : ...
+#  credentials : list of {type : credential} tuples representing credentials provided by caller to support AuthZ on method call.
+#  credentials : list of {type : credential} tuples representing credentials
+#     provided by caller to support AuthZ on method call.
 #      [NB: This argument will be omitted in descriptions below. ]
 #  options : … [ Recognized options: ….]
+#
 # Return:
+#  E.g. a list of dictionaries with these fields mandatory (…) and these fields optional (…)
+#  E.g. a list of dictionaries with these fields mandatory (…)
+#                                         and these fields optional (…)
 def fed_func (arg1, arg2, credentials, options)
 }}}
 …
      * “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.
 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.
+The 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.
 Supplementary 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.).
 …
 {{{
 #!python
+# Return information about version and options (filter, query, credential types) accepted by this service
+# Return information about version and options
+#   (e.g. filter, query, credential types) accepted by this service
+#
 # Arguments: None
 …
 {{{
 #!python
+# Creates a new instance of the given object with a ‘fields’ option specifying particular field values that are to be associated with the object.
+# These may only include those fields specified as ‘ALLOWED or ‘REQUIRED’ in the ‘Creation’ column of the object descriptions below
+# or in the “CREATE’ key in the supplemental fields in the get_version specification for that object.
+# If successful, the call returns a dictionary of the fields associated with the newly created object.
+# Creates a new instance of the given object with a ‘fields’ option
+# specifying particular field values that are to be associated with the object.
+# These may only include those fields specified as ‘ALLOWED or ‘REQUIRED’
+# in the ‘Creation’ column of the object descriptions below
+# or in the “CREATE’ key in the supplemental fields in the
+# get_version specification for that object.
+# If successful, the call returns a dictionary of the fields
+# associated with the newly created object.
+#
+#
 …
+#
 # Return:
+#   Dictionary of field/value pairs for created slice (e.g. slice URN, slice UUID, expiration and slice credential)
+#
+# Should return DUPLICATE_ERROR if creating a slice for which a non-expired slice of same name exists.
+#   Dictionary of field/value pairs for created slice
+#     (e.g. slice URN, slice UUID, expiration and slice credential)
+#
+# Should return DUPLICATE_ERROR if creating a slice for
+#   which a non-expired slice of same name exists.
 def create(type, credentials, options)
 }}}
 …
 {{{
 #!python
+# Updates an object instance specified by URN with a ‘fields’ option specifying the particular fields to update.
+# Only a single object can be updated from a single update call. The fields may include those specified as ‘Yes’ in the ‘Update’ column
+# of the object descriptions below, or ’TRUE’ in the ‘UPDATE’ key in the supplemental fields provided by the get_version call.
+# 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).
+# Updates an object instance specified by URN with a ‘fields’ option
+#  specifying the particular fields to update.
+# Only a single object can be updated from a single update call.
+# The fields may include those specified as ‘Yes’ in the ‘Update’ column
+# of the object descriptions below, or ’TRUE’ in the ‘UPDATE’ key in the
+# supplemental fields provided by the get_version call.
+# 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).
+#
 # Arguments:
 #   type: type of object to be updated
 #   urn: URN of object to update
+#
 #    Options: Contains ‘fields’ key referring dictionary of name/value pairs to update
+#   options: Contains ‘fields’ key referring dictionary of name/value pairs to update
+#
 # Return: None
+#
 …
 #!python
 # Lookup requested details for objects matching ‘match’ options.
+# 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.
+# 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.
 # If a ‘filter’ option is provided, only those attributes listed in the ‘filter’ options are returned.
 # The requirements on match criteria supported by a given service are service-specific;
+# 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).
+# 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).
+#
+# See additional details on the lookup method in the document section below.
+#
+#
 # Arguments:
 #    type: type of objects for which details are being requested
+#    options: What details to provide (filter options) for which slices (match options)
+#
+# Return: List of dictionaries (indexed by object URN) with field/value pairs for each returned object
+#    options: What details to provide (filter options)
+#            for which objects (match options)
+#
+# Return: List of dictionaries (indexed by object URN) with field/value pairs
+#   for each returned object
+#
 def lookup (type, credentials, options)
 …
+    {
        …
+       "TYPES" : ["SLICE_AUTHORITY", "MEMBER_AUTHORITY", "AGGREGATE_MANAGER", ...]
+       "TYPES" : ["SLICE_AUTHORITY", "MEMBER_AUTHORITY",
+                      "AGGREGATE_MANAGER", ...]
        …
+    }
 }}}
 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):
+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):
 || ''' Service ''' || ''' Description ''' ||
 …
 || MEMBER_AUTHORITY || An instance of the Member Authority Federation service described in this document ||
 || AGGREGATE_MANAGER || An instance of an Aggregate Manager satisfying the Aggregate Manager API ||
 || STITCHING_COMPUTATION_SERVICE || A toplogy service for supporting cross-aggregate stitching ||
+|| STITCHING_COMPUTATION_SERVICE || A topology service for supporting cross-aggregate stitching ||
 || CREDENTIAL_STORE || A service holding credentials for the federation, typically for supporting federation authentication services ||
 || LOGGING_SERVICE || A service to support federation-level event logging ||
 …
 || SERVICE_NAME || String || Short name of service || Yes || No ||
 || SERVICE_DESCRIPTION || String || Descriptive name of service || No || No ||
 || SERVICE_PEERS || URLs and version info for other running version of same service (see below) || No || No ||
 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:
+|| SERVICE_PEERS || List of Dictionaries || URLs and version info for other running version of same service (see below) || No || No ||
+The 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:
 {{{
+[
 …
 }}}
+{{{
+#!python
+# Provide a structure detailing the version information as well as details of accepted options for Registry API calls.
+#
+# Arguments:
+#   None
+#
+# Return:
+#   get_version structure information as described above
+def get_version()
+}}}
+{{{
+#!python
+# Return information about all aggregates associated with the Federation
+#
+# Arguments:
+#  options: 'match' and 'filter' options   as described in standard lookup methods
+#
+# Return:
+ #  dictionary indexed by service URN of name/value pairs for each returned service
+def lookup(options)
+}}}
+The Registry API supports these standard API methods for type="SERVICE", with elaboration in the following table:
+|| ''' Method ''' || ''' Description ''' ||
+|| lookup || lookup services matching given match criteria. ||
+Additionally, the Registry API supports the following methods:
 The 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:
 …
 || SLICE_PROJECT_URN || URN || URN of project to which slice is associated (if SA supports project) || Yes || Required (if SA supports project) || No ||
 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.
+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.
 NB: 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.
 …
 || create || Creates a  new slice with provided details  ||
 || update || Updates given slice ||
 || --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.  ||
 || lookup || lookup slicesmatching given match criteria subject to authorization restrictions. ||
+|| ~~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.  ||
+|| lookup || lookup slices matching given match criteria subject to authorization restrictions. ||
 Additionally, the Slice service provides the following methods:
 …
 {{{
 #!python
+# 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.
+#
+# 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.
+#
+# 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".
+# 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.
+#
+# 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.
+#
+# 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".
+#
 # Arguments:
 #   slice_urn: URN of slice for which to get member’s credentials
+#   options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
+#   options: Potentially contains ‘speaking-for’ key indicating a speaks-for
+# invocation (with certificate of the accountable member in the credentials argument)
 # Return:
+#   List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
+#   List of credential in “CREDENTIALS” format, i.e. a list of credentials with
+# type information suitable for passing to aggregates speaking AM API V3.
 def get_credentials(slice_urn, credentials, options)
 }}}
 …
 {{{
 #!python
+# Modify object membership, adding, removing and changing roles of members with respect to given object
+#
+# Arguments:
+#   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")
+# Modify object membership, adding, removing and changing roles of members
+#    with respect to given object
+#
+# Arguments:
+#   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")
 #   urn: URN of slice/project for which to modify membership
 #   Options:
+#       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)
+#       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)
 #       members_to_remove: List of member_urn of members to remove from slice/project
+#       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)
+#       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)
+#
 # Return:
 …
+#
 # Arguments:
+#   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")
+#   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")
 #   urn: URN of object for which to provide current members and roles
+#
 # Return:
+#    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.
+#    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.
 def lookup_members(type, urn, credentials, options)
 }}}
 …
+#
 # Return:
+#    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
+#    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
 def lookup_for_member(type, member_urn, credentials, options)
 }}}
 …
 #!python
 # Provide list of credentials (signed statements) for given member
+# This is member-specific information suitable for passing as credentials in an AM API call for aggregate authorization.
+# This is member-specific information suitable for passing as credentials in
+#  an AM API call for aggregate authorization.
 # Arguments:
 #    member_urn: URN of member for which to retrieve credentials
+#    options: Potentially contains ‘speaking-for’ key indicating a speaks-for invocation (with certificate of the accountable member in the credentials argument)
+#    options: Potentially contains ‘speaking-for’ key indicating a speaks-for
+#        invocation (with certificate of the accountable member in the credentials argument)
+#
 # Return:
+#     List of credential in “CREDENTIALS” format, i.e. a list of credentials with type information suitable for passing to aggregates speaking AM API V3.
+#     List of credential in “CREDENTIALS” format, i.e. a list of credentials with
+#        type information suitable for passing to aggregates speaking AM API V3.
 def get_credentials(member_urn, credentials, options)
 }}}