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 | |
| 182 | Each 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 | |
| 190 | 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). |
| 191 | |
| 192 | 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. |
| 193 | |
| 194 | The 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 | |
| 196 | The 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 | |
| 198 | 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. |
| 199 | |
| 200 | == API Method Examples: == |
| 201 | |
| 202 | A 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 | |
| 210 | Such 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 | |
| 234 | 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: |
| 235 | |
| 236 | { |
| 237 | |
| 238 | “fields” : { “SLICE_DESCRIPTION”: “Updated Description”, |
| 239 | |
| 240 | “SLICE_EXPIRATION”: “2013-07-29T13:15:30Z” } |
| 241 | |
| 242 | } |
| 243 | |
| 244 | An 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 | |