Changes between Version 14 and Version 15 of UniformClearinghouseAPIV2

Timestamp:

11/12/13 12:07:04 (10 years ago)

Author:

mbrinn@bbn.com

Comment:

--

UniformClearinghouseAPIV2

@@ -193 +193 @@
 || SERVER_ERROR || 101 || An error in the client/server connection ||
 
-== API Method Conventions ==
-
-Each Registry and Authority manages the state of or access to objects. Some conventions apply to similar methods across Registry or Authority services.
-
-''' Create_*Method ''' : 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.
-
-''' Update_* Method ''' : 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).
-
-''' Lookup_* Method ''' : 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).
-
-Specifically, the options argument to the lookup_* call is a dictionary. It contains an entry with key ‘match’ that contains a dictionary of name/value pairs. The names are of fields listed in the get_version for that object. The values are values for those fields to be matched. The semantics of the match is to be an “AND” (all fields must match).
+== Standard API Method ==
+
+Each Registry and Authority manages the state of or access to objects. There are some standard methods that apply to standard operations on objects of specific types. All services support the following API's for the object types that are required or provided in get_version.
+
+{{{
+#!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.
+#
+#
+# Arguments:
+#
+#    type : type of object to be created
+#   options: 
+#       'fields', a dictionary field/value pairs for object to be created
+#
+# 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.
+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).
+#
+# 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
+# Return: None
+#
+def update(type, urn, credentials, options)
+}}}
+
+{{{
+#!python
+# Deletes an object instance specified by URN 
+# Only a single object can be deleted from a single update call. 
+# Note: not all objects can be deleted. In general, it is a matter of authority policy.
+#
+# Arguments:
+#   type: type of object to be deleted
+#   urn: URN of object to delete
+#
+# Return: None
+#
+def delete(type, urn, credentials, options)
+}}}
+
+{{{
+#!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. 
+# 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).
+#
+#
+# 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
+#
+def lookup (type, credentials, options)
+}}}
+
+Some additional details on the lookup call:
+
+The options argument to the lookup_* call is a dictionary. It contains an entry with key ‘match’ that contains a dictionary of name/value pairs. The names are of fields listed in the get_version for that object. The values are values for those fields to be matched. The semantics of the match is to be an “AND” (all fields must match).
 
 The value in the dictionary of a ‘match’ option can be a list of scalars, indicating an “OR”. For example, a list of URNs provided to the SLICE_URN key would match any slice with any of the listed URNs.
@@ -213 +280 @@
 If a lookup method asks for information about objects whose disclosure is prohibited to the requestor by policy, the method must not return the data. It is implementation specified as to whether the call should return an error, return a dictionary with the URN key pointing to an empty dictionary, or have no URN key in the returned dictionary.
 
+
 == API Method Examples: ==
 
-A Member Authority (MA) manages information about member objects. The MA method lookup_member could take an options argument such as
+A Member Authority (MA) manages information about member objects. The MA method lookup(type="MEMBER") could take an options argument such as
 
 {
@@ -247 +315 @@
 }
 
-A Slice Authority (SA) manages information about slice objects. The SA method update_slice could take an options ‘update’ argument such as to change the slice description and extend the slice expiration:
+A Slice Authority (SA) manages information about slice objects. The SA method update(type="SLICE") could take an options ‘update’ argument such as to change the slice description and extend the slice expiration:
 
 {
@@ -257 +325 @@
 }
 
-An example of lookup_slice that wanted to retrieve the slice names for a list of slice URNs could specify options:
+An example of lookup(type="SLICE)") at an SA that wanted to retrieve the slice names for a list of slice URNs could specify options:
 
 {“match”: {
@@ -278 +346 @@
 == API Method Examples (cont.): ==
 
-An example of create_slice call would specify required options e.g.:
+An example of create(type="SLICE") call would specify required options e.g.:
 
 {