Changes between Version 14 and Version 15 of UniformClearinghouseAPIV2


Ignore:
Timestamp:
11/12/13 12:07:04 (6 years ago)
Author:
mbrinn@bbn.com
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPIV2

    v14 v15  
    193193|| SERVER_ERROR || 101 || An error in the client/server connection ||
    194194
    195 == API Method Conventions ==
    196 
    197 Each Registry and Authority manages the state of or access to objects. Some conventions apply to similar methods across Registry or Authority services.
    198 
    199 ''' 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.
    200 
    201 ''' 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).
    202 
    203 ''' 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).
    204 
    205 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).
     195== Standard API Method ==
     196
     197Each 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.
     198
     199{{{
     200#!python
     201# Creates a new instance of the given object with a ‘fields’ option specifying particular field values that are to be associated with the object.
     202# These may only include those fields specified as ‘ALLOWED or ‘REQUIRED’ in the ‘Creation’ column of the object descriptions below
     203# or in the “CREATE’ key in the supplemental fields in the get_version specification for that object.
     204# If successful, the call returns a dictionary of the fields associated with the newly created object.
     205#
     206#
     207# Arguments:
     208#
     209#    type : type of object to be created
     210#   options:
     211#       'fields', a dictionary field/value pairs for object to be created
     212#
     213# Return:
     214#   Dictionary of field/value pairs for created slice (e.g. slice URN, slice UUID, expiration and slice credential)
     215#
     216# Should return DUPLICATE_ERROR if creating a slice for which a non-expired slice of same name exists.
     217def create(type, credentials, options)
     218}}}
     219
     220{{{
     221#!python
     222# Updates an object instance specified by URN with a ‘fields’ option specifying the particular fields to update.
     223# Only a single object can be updated from a single update call. The fields may include those specified as ‘Yes’ in the ‘Update’ column
     224# of the object descriptions below, or ’TRUE’ in the ‘UPDATE’ key in the supplemental fields provided by the get_version call.
     225# 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).
     226#
     227# Arguments:
     228#   type: type of object to be updated
     229#   urn: URN of object to update
     230#
     231#    Options: Contains ‘fields’ key referring dictionary of name/value pairs to update
     232# Return: None
     233#
     234def update(type, urn, credentials, options)
     235}}}
     236
     237{{{
     238#!python
     239# Deletes an object instance specified by URN
     240# Only a single object can be deleted from a single update call.
     241# Note: not all objects can be deleted. In general, it is a matter of authority policy.
     242#
     243# Arguments:
     244#   type: type of object to be deleted
     245#   urn: URN of object to delete
     246#
     247# Return: None
     248#
     249def delete(type, urn, credentials, options)
     250}}}
     251
     252{{{
     253#!python
     254# Lookup requested details for objects matching ‘match’ options.
     255# 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.
     256# If a ‘filter’ option is provided, only those attributes listed in the ‘filter’ options are returned.
     257# The requirements on match criteria supported by a given service are service-specific;
     258# 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).
     259#
     260#
     261# Arguments:
     262#    type: type of objects for which details are being requested
     263#    options: What details to provide (filter options) for which slices (match options)
     264#
     265# Return: List of dictionaries (indexed by object URN) with field/value pairs for each returned object
     266#
     267def lookup (type, credentials, options)
     268}}}
     269
     270Some additional details on the lookup call:
     271
     272The 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).
    206273
    207274The 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.
     
    213280If 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.
    214281
     282
    215283== API Method Examples: ==
    216284
    217 A Member Authority (MA) manages information about member objects. The MA method lookup_member could take an options argument such as
     285A Member Authority (MA) manages information about member objects. The MA method lookup(type="MEMBER") could take an options argument such as
    218286
    219287{
     
    247315}
    248316
    249 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:
     317A 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:
    250318
    251319{
     
    257325}
    258326
    259 An example of lookup_slice that wanted to retrieve the slice names for a list of slice URNs could specify options:
     327An example of lookup(type="SLICE)") at an SA that wanted to retrieve the slice names for a list of slice URNs could specify options:
    260328
    261329{“match”: {
     
    278346== API Method Examples (cont.): ==
    279347
    280 An example of create_slice call would specify required options e.g.:
     348An example of create(type="SLICE") call would specify required options e.g.:
    281349
    282350{