Changes between Version 25 and Version 26 of UniformClearinghouseAPIV2


Ignore:
Timestamp:
12/10/13 09:56:36 (6 years ago)
Author:
mbrinn@bbn.com
Comment:

Update to reflect comment #1 of Wim's feedback

Legend:

Unmodified
Added
Removed
Modified
  • UniformClearinghouseAPIV2

    v25 v26  
    8080
    8181Each Registry or Authority 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):
    82  * VERSION: A string with the version number of the Federation API (e.g. “1”). Note: this is the version of the API not the version of the implementation. This field is mandatory for all services.
     82 * VERSION: A string with the version number of the Federation API (e.g. “2”, the version for this document). Note: this is the version of the API not the version of the implementation. This field is mandatory for all services.
    8383 * URN : The URN of the service being contacted. This field is mandatory for SA and MA services, optional for Registry service.
    8484 * IMPLEMENTATION: A string with the version number of the implementation of this service (format implementation specific). This field is optional for services.
    85  * SERVICES: The set of services the given URL supports  
    86  * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [geni_abac, geni_abac]) and list of supported credential versions on protected API methods.  Format is analogous to that in the AM API: a list of {"type": cred_type, "version" : cred_version} dictionaries of all supported credential types and versions. ''[Authorities only]''
    87  * ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership).  ''[SA only]''
     85 * SERVICES: The list of names of services the given URL supports. This field is optional (with default being the default service for that authority, i.e. SERVICE for Federation Registry, SLICE for Slice Authority, MEMBER for MemberAuthority). 
     86 * CREDENTIAL_TYPES: A list of recognized credential types (e.g. [geni_sfa, geni_abac]) and list of supported credential versions on protected API methods.  Format is analogous to that in the AM API: a list of {"type": cred_type, "version" : cred_version} dictionaries of all supported credential types and versions. ''[Required for Authorities only]''
     87 * ROLES : A list of recognized roles for slice/project membership (optional for those Slice Authorities supporting membership).  ''[Required for SA only]''
    8888 * FIELDS: A dictionary of object field names (i.e. in additional to the required fields) and associated attributes including:
    89      * “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 Registry). This field is mandatory for any field listed.
     89     * “OBJECT” provides the object type to which the field belongs. The field is optional for fields of the default authority object (i.e. SLICE for Slice Authority, MEMBER for Member Authority, SERVICE for Federation Registry) but mandatory for all other fields.
    9090     * “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.] This field is mandatory for any field listed.
    9191     * “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. This attribute is optional for listed fields.
    9292     * "MATCH" attributes may be specified as booleans TRUE or FALSE (default = TRUE). These indicate whether a given field may be specified in an match option of a lookup call. This attribute is optional for listed fields.
    9393     * “UPDATE” attributes may be specified as booleans TRUE or FALSE (default = FALSE). These indicate whether the given field may be specified in an update call. This attribute is optional for listed fields.
    94      * “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. The default, if not provided, is "PUBLIC", and thus this attribute is optional.
     94     * “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. The default, if not provided, is "PUBLIC", and thus this attribute is optional.
    9595
    9696The FIELDS element of the get_version should contain all supplementary (non-mandatory) field objects supported by a given service. Additionally, it may contain mandatory field objects for which the default semantics (for "CREATE", "MATCH", "UPDATE", "PROTECT") should be overridden. The FIELDS element is thus optional for all services.
    9797
    98 Supplementary field names should be placed in a distinct namespace by a prefix unique to that federation, and starting with an underscore (e.g _GENI_,  _OFELIA_ , _FED4FIRE_ or _PROTOGENI_ etc.).
     98Supplementary field names should be placed in a distinct namespace by a prefix unique to that federation, and starting with an underscore (e.g. _GENI_,  _OFELIA_ , _FED4FIRE_ or _PROTOGENI_ etc.).
    9999
    100100The return from the get_version call will be used to construct and validate options to Registry and Authority API calls, as described in subsequent sections.
     
    122122{
    123123
    124 “VERSION”: “10.0.7”,
     124“VERSION”: “2”,
    125125
    126126“SERVICES”: [“SLICE”, “PROJECT”, “SLICE_MEMBER”, “PROJECT_MEMBER”],
     
    148148{
    149149
    150       “VERSION”: “10.0.7”,
     150      “VERSION”: “2”,
    151151
    152152      “CREDENTIAL_TYPES”:  [{"type" : "geni_sfa", version" : 2}, {"type" : "geni_sfa", "version" : "3"}, {"type" : "geni_abac", "version" : "1"}]
     
    182182
    183183{
    184       “VERSION”: “10.0.7”,
     184      “VERSION”: “2”,
    185185
    186186      “FIELDS”: {
     
    231231#
    232232# Return:
    233 #   Dictionary of field/value pairs for created slice
    234 #     (e.g. slice URN, slice UUID, expiration and slice credential)
    235 #
    236 # Should return DUPLICATE_ERROR if creating a slice for
    237 #   which a non-expired slice of same name exists.
     233#   Dictionary of object-type specific field/value pairs for created object
     234#
     235#
    238236def create(type, credentials, options)
    239237}}}
     
    253251#   type: type of object to be updated
    254252#   urn: URN of object to update
     253#     (Note: this may be a non-URN-formatted unique identifier e.g. in the case of keys)
    255254#   options: Contains ‘fields’ key referring dictionary of
    256255#        name/value pairs to update
     
    264263#!python
    265264# Deletes an object instance specified by URN
    266 # Only a single object can be deleted from a single update call.
     265# Only a single object can be deleted from a single delete call.
    267266# Note: not all objects can be deleted. In general, it is a matter
    268267#     of authority policy.
     
    271270#   type: type of object to be deleted
    272271#   urn: URN of object to delete
     272#     (Note: this may be a non-URN-formatted unique identifier e.g. in the case of keys)
    273273#
    274274# Return: None
     
    581581NB: SLICE_NAME must adhere to the restrictions for slice names in the Aggregate Manager (AM) API, namely that it must be <= 19 characters, only alphanumeric plus hyphen, no leading hyphen.
    582582
    583 The Sliver Info Service supports these standard API methods for type="SLIVER_INFO":
     583The Slice Service supports these standard API methods for type="SLICE":
    584584
    585585|| ''' Method ''' || ''' Description ''' ||