Changes between Version 1 and Version 2 of UniformClearinghouseAPI


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

--

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPI

    v1 v2  
    6161''Perform method ‘ch_func’''
    6262
     63'''Arguments'''
     64   argl ''' : ''' ...
     65
     66credentials : list of {type : credential} tuples representing credentials provided by caller to support AuthZ on method call.
     67[NB: This argument will be omitted in descriptions below. ]
     68options : … [ Recognized options: ….]
     69
     70''' Return ''': E.g. a list of dictionaries with these fields mandatory (…) and these fields optional (…)
     71
     72*/
     73
     74function ''' ch_func ''' (arg1, arg2, credentials, options)
     75
     76== API 'get_version' methods ==
     77
     78Different Clearinghouses will provide different sets of methods bundled into services. Further, they will manage different kinds of objects and support different details for these objects.
     79
     80The CH 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):
     81 * VERSION: The version number of the API (e.g. “10.0.7”)
     82 * SERVICES: The set of services the given URL supports (only for Slice Authority)
     83 * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [ABAC, SFA]) on protected API methods.
     84 * ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership)
     85 * FIELDS: A dictionary of '''''supplementary''''' object field names (i.e. in additional to the required fields) and associated attributes including:
     86     * “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 Clearinghouse)
     87     * “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.]
     88     * “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.
     89     * “UPDATE” attributes may be specified as TRUE or FALSE (default = FALSE). These indicate whether the given field may be specified in an update call.
     90     * “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.
     91
     92The return from the get_version call will be used to construct and validate options to CH and Authority API calls, as described in subsequent sections.
     93
     94The following page provides some example returns from different get_version calls.
     95
     96== Example get_version returns: ==
     97
     98The following is an example of a return from a get_version for an SA. The responses are all dictionaries via XMLRPC into the native implementation. They are shown here in JSON-like syntax: