Context Navigation

Changes between Version 25 and Version 26 of UniformClearinghouseAPIV2

Timestamp:: 12/10/13 09:56:36 (10 years ago)
Author:: mbrinn@bbn.com
Comment:: Update to reflect comment #1 of Wim's feedback

Legend:

: Unmodified
: Added
: Removed
: Modified

UniformClearinghouseAPIV2

-                      v25
+                      v26
 Each Registry or Authority API provides a ‘get_version’ method, which provides information to the caller (or a tool composing calls for a tool user) about versions and options supported by that API. The call takes no argument and is unguarded (anyone can call it). The return from the get_version call will be a dictionary including the following entries (by key):
  * VERSION: A string with the version number of the Federation API (e.g. “1”). Note: this is the version of the API not the version of the implementation. This field is mandatory for all services.
+ * VERSION: A string with the version number of the Federation API (e.g. “2”, the version for this document). Note: this is the version of the API not the version of the implementation. This field is mandatory for all services.
  * URN : The URN of the service being contacted. This field is mandatory for SA and MA services, optional for Registry service.
  * IMPLEMENTATION: A string with the version number of the implementation of this service (format implementation specific). This field is optional for services.
  * SERVICES: The set of services the given URL supports
  * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [geni_abac, geni_abac]) and list of supported credential versions on protected API methods.  Format is analogous to that in the AM API: a list of {"type": cred_type, "version" : cred_version} dictionaries of all supported credential types and versions. ''[Authorities only]''
  * ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership).  ''[SA only]''
+ * SERVICES: The list of names of services the given URL supports. This field is optional (with default being the default service for that authority, i.e. SERVICE for Federation Registry, SLICE for Slice Authority, MEMBER for MemberAuthority).
+ * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [geni_sfa, geni_abac]) and list of supported credential versions on protected API methods.  Format is analogous to that in the AM API: a list of {"type": cred_type, "version" : cred_version} dictionaries of all supported credential types and versions. ''[Required for Authorities only]''
+ * ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership).  ''[Required for SA only]''
  * FIELDS: A dictionary of object field names (i.e. in additional to the required fields) and associated attributes including:
      * “OBJECT” provides the object to which the field belongs (if not the default authority object, i.e. SLICE for Slice Authority, MEMBER for Member Authority, SERVICE for Registry). This field is mandatory for any field listed.
+     * “OBJECT” provides the object type to which the field belongs. The field is optional for fields of the default authority object (i.e. SLICE for Slice Authority, MEMBER for Member Authority, SERVICE for Federation Registry) but mandatory for all other fields.
      * “TYPE” may be one of “URN”, “UID”, “STRING”, “DATETIME”, “EMAIL”, “KEY”,“BOOLEAN”, “CREDENTIAL”, “CERTIFICATE”. [NB. This set of types subject to change. See Appendix for more information on these data types.] This field is mandatory for any field listed.
      * “CREATE” attributes may be specified as “REQUIRED”, “ALLOWED” or “NOT ALLOWED” (default = “NOT ALLOWED”). These indicate whether the given supplementary field is required, allowed or prohibited in create calls. This attribute is optional for listed fields.
      * "MATCH" attributes may be specified as booleans TRUE or FALSE (default = TRUE). These indicate whether a given field may be specified in an match option of a lookup call. This attribute is optional for listed fields.
      * “UPDATE” attributes may be specified as booleans TRUE or FALSE (default = FALSE). These indicate whether the given field may be specified in an update call. This attribute is optional for listed fields.
      * “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.
+     * “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 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.).
+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.).
 The return from the get_version call will be used to construct and validate options to Registry and Authority API calls, as described in subsequent sections.
 …
+{
 “VERSION”: “10.0.7”,
+“VERSION”: “2”,
 “SERVICES”: [“SLICE”, “PROJECT”, “SLICE_MEMBER”, “PROJECT_MEMBER”],
 …
+{
       “VERSION”: “10.0.7”,
+      “VERSION”: “2”,
       “CREDENTIAL_TYPES”:  [{"type" : "geni_sfa", version" : 2}, {"type" : "geni_sfa", "version" : "3"}, {"type" : "geni_abac", "version" : "1"}]
 …
+{
       “VERSION”: “10.0.7”,
+      “VERSION”: “2”,
       “FIELDS”: {
 …
+#
 # 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 object-type specific field/value pairs for created object
+#
+#
 def create(type, credentials, options)
 }}}
 …
 #   type: type of object to be updated
 #   urn: URN of object to update
+#     (Note: this may be a non-URN-formatted unique identifier e.g. in the case of keys)
 #   options: Contains ‘fields’ key referring dictionary of
 #        name/value pairs to update
 …
 #!python
 # Deletes an object instance specified by URN
 # Only a single object can be deleted from a single update call.
+# Only a single object can be deleted from a single delete call.
 # Note: not all objects can be deleted. In general, it is a matter
 #     of authority policy.
 …
 #   type: type of object to be deleted
 #   urn: URN of object to delete
+#     (Note: this may be a non-URN-formatted unique identifier e.g. in the case of keys)
+#
 # Return: None
 …
 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.
 The Sliver Info Service supports these standard API methods for type="SLIVER_INFO":
+The Slice Service supports these standard API methods for type="SLICE":
 || ''' Method ''' || ''' Description ''' ||