| | 63 | '''Arguments''' |
| | 64 | argl ''' : ''' ... |
| | 65 | |
| | 66 | credentials : 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. ] |
| | 68 | options : … [ Recognized options: ….] |
| | 69 | |
| | 70 | ''' Return ''': E.g. a list of dictionaries with these fields mandatory (…) and these fields optional (…) |
| | 71 | |
| | 72 | */ |
| | 73 | |
| | 74 | function ''' ch_func ''' (arg1, arg2, credentials, options) |
| | 75 | |
| | 76 | == API 'get_version' methods == |
| | 77 | |
| | 78 | Different 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 | |
| | 80 | The 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 | |
| | 92 | The 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 | |
| | 94 | The following page provides some example returns from different get_version calls. |
| | 95 | |
| | 96 | == Example get_version returns: == |
| | 97 | |
| | 98 | The 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: |
