Changes between Version 16 and Version 17 of NewTestbedAPISpec


Ignore:
Timestamp:
Aug 12, 2013 1:23:48 PM (7 years ago)
Author:
faber
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • NewTestbedAPISpec

    v16 v17  
    406406       * Userid - a member's userid
    407407       * rights - a 32-bit integer encoding the user's rights (each a flag)
    408          * ADD_USER - right to add a user to this group
    409          * REMOVE_USER - right to remove a user from this group
    410          * REALIZE_EXPERIMENT - the right to realize an experiment under this group
     408         * ADD_USER - right to add a user to this project
     409         * REMOVE_USER - right to remove a user from this project
     410         * CREATE_CIRCLE - the right to create a circle under this project's name space
    411411     * Approved - a flag indicating this project has been approved
    412412
     
    685685
    686686Generally an removing a project requires a testbed administrator.
     687
     688== Circles ==
     689
     690The profile API lets users manage their circle memberships as well as manipulate circles.  The circles API is similar to the Projects API.  The primary exceptions are that there is no approval process for circles (though there is for joining or adding a user) and that the permissions are different.
     691
     692These calls work on all circles '''except''' those linked to a project.  Those circles must have their membership, ownership, and permissions manipulated through the project to ensure that the contents remain synchronized.
     693
     694=== Listing Circles ===
     695
     696Authenticated users can look at the various circles they are members of, and may scope such searcher by circle names.
     697
     698 * '''Service:''' Circles
     699 * '''Operation:''' viewCircles
     700 * '''Input Parameters:'''
     701   * Userid - the requester's userid
     702   * Owner - a userid - only find circles owned by this user
     703   * NameRE - a string containing a regular expression to match against circle names
     704 * '''Return Values:'''
     705   * A list of circle descriptors containing
     706     * Name - a string contaiing the circle name
     707     * Owner - the uid of the circle owner
     708     * Members - an array of structures containing
     709       * Userid - a member's userid
     710       * rights - a 32-bit integer encoding the user's rights (each a flag)
     711         * ADD_USER - right to add a user to this circle
     712         * REMOVE_USER - right to remove a user from this circle
     713         * REALIZE_EXPERIMENT - the right to realize an experiment under this circle
     714
     715Filters are cumulative: specifying a regular expression and an owner will match on both.
     716
     717=== Changing Circle Membership ===
     718
     719With appropriate rights a user can add another user to a circle they are in.
     720The user being added must confirm this addition (below).  As a result of this call, users being added will be sent a notification including a challenge id to respond to, similar to a password change URL.  The prefix for that URL can be passed in here.
     721
     722 * '''Service:''' Circles
     723 * '''Operation:''' addUsers
     724 * '''Input Parameters:'''
     725   * CircleID - the circle
     726   * Uids - the userids to add
     727   * Perms - the permissions to grant the user in this circle.  The values are given here.
     728   * urlPrefix - a prefix to direct the user to a specific web interface to respond to the challenge.
     729 * '''Return Values:'''
     730   * A list of results of the form
     731     * Name - the uid being added
     732     * Success - a flag indicating success or failure
     733     * Reason - the reason for a failure
     734
     735For each user successfully added, a notification is sent.  To respond to that notification the UI must call:
     736
     737* '''Service:''' Circles
     738 * '''Operation:''' addUserConfirm
     739 * '''Input Parameters:'''
     740   * ChallengeID - the challenge being responded to
     741 * '''Return Values:'''
     742   * true if the user was added.  A fault is thrown on errors.
     743
     744Administrators can add users without going through the confirmation process:
     745
     746* '''Service:''' Circles
     747 * '''Operation:''' addUsersNoConfirm
     748 * '''Input Parameters:'''
     749   * CircleID - the circle
     750   * Uids - the userids to add
     751   * Perms - the permissions to grant the user in this circle.  The values are given here.
     752 * '''Return Values:'''
     753   * A list of results of the form
     754     * Name - the uid being added
     755     * Success - a flag indicating success or failure
     756     * Reason - the reason for a failure
     757
     758Users can also request to join a circle.  This requires some member of the circle with ADD_USER rights to agree, so a notification is sent to all such users.
     759
     760 * '''Service:''' Circles
     761 * '''Operation:''' joinCircle
     762 * '''Input Parameters:'''
     763   * Uid - the uid to add
     764   * CircleID - the circle to join
     765   * urlPrefix - a prefix to direct the user to a specific web interface to respond to the challenge.
     766 * '''Return Values:'''
     767   * None
     768
     769The join succeeds when a user with appropriate permissions calls joinCircleConfirm.
     770Note that the user calling joinCircleConfirm sets the new user's circle permissions.
     771
     772* '''Service:''' Circles
     773 * '''Operation:''' joinCircleConfirm
     774 * '''Input Parameters:'''
     775   * ChallengeID - the challenge being responded to
     776   * Perms - the permissions to grant the user in this circle.  The values are given here.
     777 * '''Return Values:'''
     778   * true if the user was subsequently added.  A fault is thrown on errors.
     779
     780
     781Users can be removed from circles:
     782
     783 * '''Service:''' Circles
     784 * '''Operation:''' removeUsers
     785 * '''Input Parameters:'''
     786   * CircleName - the circle to change
     787   * Uids - uids to remove
     788 * '''Return Values:'''
     789   * A list of results of the form
     790     * Name - the uid being added
     791     * Success - a flag indicating success or failure
     792     * Reason - the reason for a failure
     793
     794If a user has the right to both add and remove a user, that user can change a user's permissions:
     795
     796 * '''Service:''' Circles
     797 * '''Operation:''' changePermissions
     798 * '''Input Parameters:'''
     799   * CircleName - the circle to change
     800   * Uids - the uids to manipulate
     801   * Rights - a 32-bit integer encoding the user's rights (each a flag)
     802 * '''Return Values:'''
     803   * A list of results of the form
     804     * Name - the uid being added
     805     * Success - a flag indicating success or failure
     806     * Reason - the reason for a failure
     807
     808=== Manipulating Circles ===
     809
     810The owner of a group (and only the owner of that group) can give that privilege away to another member:
     811
     812 * '''Service:''' Circles
     813 * '''Operation:''' setOwner
     814 * '''Input Parameters:'''
     815   * Userid - the requester's userid
     816   * CircleName - the circle to change
     817   * NewOwner - the uid of the new owner
     818 * '''Return Values:'''
     819   * None
     820
     821=== Circle Profiles ===
     822
     823The calls for manipulating a circle profile are very similar to user profiles:
     824
     825To get a profile schema, for example to create an empty web page,
     826
     827 * '''Service:''' Circles
     828 * '''Operation:''' getProfileDescription
     829 * '''Input Parameters:'''
     830 * '''Return Values:'''
     831   * Circleid - always empty
     832   * A list of profile elements each containing
     833     * Name - a string, the element's name
     834     * DataType - a string giving the element's
     835       * string
     836       * integer
     837       * double
     838       * binary/opaque
     839     * Value - a string containing the element's value
     840     * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
     841       * READ_WRITE
     842       * READ_ONLY
     843       * WRITE_ONLY (e.g., password)
     844     * Optional - a flag true if the field is optional (must be present but may be empty)
     845     * Removable - a flag true if the field can be removed
     846     * Description - a string explaining the field
     847     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
     848     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
     849     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     850     * LengthHint - an integer suggesting how long an input firld should be presented
     851
     852To read a circle's profile.
     853
     854 * '''Service:''' Circles
     855 * '''Operation:''' getCircleProfile
     856 * '''Input Parameters:'''
     857  * userid - a string naming the user to be retrieved
     858 * '''Return Values:'''
     859   * Circleid - the user whose profile is returned
     860   * A list of profile elements each containing
     861     * Name - a string, the element's name
     862     * DataType - a string giving the element's
     863       * string
     864       * integer
     865       * double
     866       * binary/opaque
     867     * Value - a string containing the element's value
     868     * Access - a 32-bit integer describing the access values (values at [http://www.isi.edu/~faber/tmp/doc/net/deterlab/testbed/user/UserAttribute.html Attribute's javadoc])
     869       * READ_WRITE
     870       * READ_ONLY
     871       * WRITE_ONLY (e.g., password)
     872     * Optional - a flag true if the field is optional (must be present but may be empty)
     873     * Removable - a flag true if the field can be removed
     874     * Description - a string explaining the field
     875     * Format - a regular expression that can be used to validate the field entry (may be null, and generally is for optional fields)
     876     * FormatDescription - A brief, natural language description of the field input constraints, e.g. "A valid e-mail address" or "only numbers and spaces".
     877     * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     878     * LengthHint - an integer suggesting how long an input field should be presented
     879
     880Finally a user can modify a circle profile:
     881
     882 * '''Service:''' Circles
     883 * '''Operation:''' changeCircleProfile
     884 * '''Input Parameters:'''
     885   * CircleId - the circle's profile to modify
     886   * A list of change requests. Each request contains
     887     * Name - the name of the field to change
     888     * Value - the new value of the field
     889     * Delete - a flag, if true delete the field rather than modify it
     890 * '''Return Values:'''
     891   * A list of responses each containing
     892    * Name - astring with the name of the field
     893    * Success - a flag indicating if the request succeeded
     894    * Reason - a string indicating the reason if Success is false
     895
     896
     897=== Manipulating Profile Attributes ===
     898
     899Administrators may add attributes to circle profiles or remove them.  That is to say, add a schema (including format constraints and descriptions), not set a value for a circle.
     900Creating an attribute:
     901
     902* '''Service:''' Circles
     903 * '''Operation:''' createCircleAttribute
     904 * '''Input Parameters:'''
     905   * Name - the attribute name
     906   * Type - the type (STRING, INT, FLOAT, OPAQUE)
     907   * Optional - a boolean, true if this attribute is optional
     908   * Access - an integer the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
     909   * Description - natural language description of the field (optional)
     910   * Format - a regular expression describing the format (optional)
     911   * Formatdescription - a natural language explanation of the format (optional)
     912   * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     913   * LengthHint - an integer suggesting how long an input
     914   * Def - default value of the attribute (will be set for all users)
     915 * '''Return Values:'''
     916  * a boolean, true if the attribute was created
     917
     918And removing an attribute:
     919
     920* '''Service:''' Circles
     921 * '''Operation:''' removeCircleAttribute
     922 * '''Input Parameters:'''
     923   * Name - the attribute name
     924 * '''Return Values:'''
     925  * a boolean, true if the attribute was removed
     926
     927Finally administrators can modify profile attributes:
     928
     929* '''Service:''' Circles
     930 * '''Operation:''' modifyCircleAttribute
     931 * '''Input Parameters:'''
     932   * Name - the attribute name
     933   * Type - the type (STRING, INT, FLOAT, OPAQUE)
     934   * Optional - a boolean, true if this attribute is optional
     935   * Access - an integer the user's ability to modify (READ_WRITE, READ_ONLY, WRITE_ONLY, NO_ACCESS)
     936   * Description - natural language description of the field (optional)
     937   * Format - a regular expression describing the format (optional)
     938   * Formatdescription - a natural language explanation of the format (optional)
     939   * OrderingHint - an integer suggesting where to present the attribute. Lower numbers come first
     940   * LengthHint - an integer suggesting how long an input
     941 * '''Return Values:'''
     942  * a boolean, true if the attribute was created
     943
     944
     945=== Creating and Deleting Circles ===
     946
     947Creating and removing circles are also similar to creating and removing users:
     948
     949 * '''Service:''' Circles
     950 * '''Operation:''' createCircle
     951 * '''Input Parameters:'''
     952   * CircleId - the new circle's name
     953   * Uid - the new owner's uid (usually the caller)
     954   * profile - a list of attributes that will make up the circle's profile
     955   * A list of profile elements each containing
     956     * Name - a string, the element's name
     957     * StringValue - a string containing the element's value
     958 * '''Return Values:'''
     959   * None
     960
     961As with users, all required (non-optional) fields in the profile must be provided.  The circle will be created, and can be used immediately.
     962
     963Removing a circle is straightforward.
     964
     965 * '''Service:''' Circles
     966 * '''Operation:''' removeCircle
     967 * '''Input Parameters:'''
     968   * Userid - the requester's userid
     969   * Name - the new circle's name
     970 * '''Return Values:'''
     971   * None
    687972
    688973== Experiments ==