Changes between Version 8 and Version 9 of UniformClearinghouseAPI


Ignore:
Timestamp:
08/14/13 15:31:56 (11 years ago)
Author:
jmccolga@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPI

    v8 v9  
    172172|| NONE || 0 || No error encountered – the return value is a successful result. An empty list form a query should be interpreted as ‘nothing found matching criteria’. ||
    173173|| AUTHENTICATION_ERROR || 1 || The invoking tool or member did not provide appropriate credentials indicating that they are known to the CH or that they possessed the private key of the entity they claimed to be ||
    174 ||
    175 ||
    176 ||
    177 ||
    178 ||
     174|| AUTHORIZATION_ERROR || 2 || The invoking tool or member does not have the authority to invoke the given call with the given arguments ||
     175|| ARGUMENT_ERROR || 3 || The arguments provided to the call were mal-formed or mutually inconsistent. ||
     176|| DATABASE_ERROR || 4 || An error from the underlying database was returned. (More info should be provided in the ‘output’ return value] ||
     177|| NOT_IMPLEMENTED_ERROR || 100 || The given method is not implemented on the server. ||
     178|| SERVER_ERROR || 101 || An error in the client/server connection ||
     179
     180== API Method Conventions ==
     181
     182Each CH and Authority manages the state of or access to objects. Some conventions apply to similar methods across CH or Authority services.
     183
     184''' 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.
     185
     186''' 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).
     187
     188''' 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.
     189
     190Specifically, 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).
     191
     192The 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.
     193
     194The options argument may include an additional dictionary keyed “filter” which is a list of fields associated with that object type (again, as specified in the get_version entry for that object). No “filter” provided means all fields are to be returned.
     195
     196The return of the call will be a dictionary of dictionaries, one per matching object indexed by URN, of fields matching the filter criteria. If the query found no matches, an empty dictionary is returned (i.e. no error is reported, assuming no other error was encountered in processing).
     197
     198If 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.
     199
     200== API Method Examples: ==
     201
     202A Member Authority (MA) manages information about member objects. The MA method lookup_member could take an options argument such as
     203
     204{
     205
     206      "match”: {“MEMBER_LASTNAME”: “BROWN”},
     207     
     208      "filter”: [“MEMBER_EMAIL”, “MEMBER_FIRSTNAME”]
     209
     210Such a call would find any member with last name Brown and return a dictionary keyed by the member URN containing a dictionary with their email, and first name.
     211
     212''' { '''
     213
     214      “urn:publicid:IDN+mych+user+abrown” :
     215     
     216            {“MEMBER_EMAIL”: abrown@williams.edu,
     217           
     218            “MEMBER_FIRSTNAME”: “Arlene”},
     219     
     220      “urn:publicid:IDN+mych+user+mbrown” :
     221
     222            {“MEMBER_EMAIL”: mbrown@umass.edu,
     223
     224            “MEMBER_FIRSTNAME”: “Michael”},
     225
     226      “urn:publicid:IDN+mych+user+sbrown” :
     227
     228            {“MEMBER_EMAIL”: sbrown@stanford.edu,
     229
     230            “MEMBER_FIRSTNAME”: “Sam”}
     231
     232}
     233
     234A 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:
     235
     236{
     237
     238      “fields” : { “SLICE_DESCRIPTION”: “Updated Description”,
     239
     240                 “SLICE_EXPIRATION”: “2013-07-29T13:15:30Z” } 
     241
     242}
     243
     244An example of lookup_slice that wanted to retrieve the slice names for a list of slice URNs could specify options:
     245
     246{“match”: {
     247
     248      “SLICE_URN”: [
     249
     250             “urn:publicid+IDN+this_sa:myproject+slice+slice1”,
     251
     252             “urn:publicid+IDN+this_sa:myproject+slice+slice2”,
     253
     254             “urn:publicid+IDN+this_sa:myproject+slice+slice3”
     255
     256       ]},
     257
     258“filter”: [“SLICE_NAME”]
     259
     260}
     261 
     262