Using the Dot Net Dash Membership Management REST API

When the Dot Net Dash control is rendered onto a web page, a "Route" is registered (using System.Web.Routing) that directs client requests to an MVC Controller which implements the Membership Management API that is called by the Silverlight-based client.

You can leverage this API in your own Silverlight or AJAX applications to retrieve or manage Membership, Role and Profile information.

About the MVC Controller

Dot Net Dash includes an Asp.Net MVC Controller called "web_managementController" that includes a number of methods such as "GetUser" and "ChangePassword". Due to the sensitive nature of these methods, the controller will only respond to requests from an authenticated user that is in a defined (Administrative) role. While an SSL connection is not required, it is recommended.

The path to the controller is defined by the ControllerPath property of the Dot Net Dash control which is "web_management.aspx" by default.

You can call controller methods by entering an address like this:
http://yoursite.com/web_management.aspx/{methodName}

Web Management API Methods

Each of the methods returns either a JSON or XML response with the following information:

  • ErrorCode - (always zero)
  • Success - (true/false)
  • Message - (string value with information about any errors)
  • Data - (serialized object representing results of method)

For most methods, you can request either a JSON or XML response by adding the querystring parameter "format=json" or "format=xml" (xml is the default.)

Membership methods
GetUser?userName={value} Given a valid Membership Username, Data will contain a MemberInfo object with the following:
  • UserId (string)
  • Username (string)
  • Email (string)
  • IsApproved (bool)
  • CreationDate (DateTime)
  • IsLockedOut (bool)
  • LastLoginDate (DateTime)
  • LastActivityDate (DateTime)
  • Password (string if enabled)
  • PasswordFormat (int)
  • PasswordSalt (string)
  • FailedPasswordAttemptCount (int)
  • FailedPasswordAnswerAttemptCount (int)
  • LastPasswordChangedDate (DateTime)
  • Question (string)
  • PasswordAnswer (string if enabled)
  • Comments (string)
  • CreationDateLabel (string, formatted date)
  • LastLoginDateLabel (string, formatted date)
  • LastActivityDateLabel (string, formatted date)
  • LastPasswordChangedDateLabel (formatted date)
  • IsApprovedLabel (string, formatted Yes/No)
  • ProfileInfo (object, see GetProfileInfo)
  • RoleInfo (object, see GetRoleInfo)
GetNewUser Returns an empty MemberInfo object (see GetUser.) This method can be used to retrieve an object that can be loaded and submitted to the CreateUser method (see below.)
FindUsers?
[Roles=role1,role2]
[&IsLockedOut={true/false}]
[&IsApproved={true/false}]
[&LastLogin=DateSearchOperator]
[&LastLoginDate={Date}]
[&LastLoginDateEnd={Date}]
[&Created=DateSearchOperator]
[&CreateDate={Date}]
[&CreateDateEnd={Date}]
[&FindMode={FindMode}] 		Get or Post parameters (shown at left and which are interpreted as MembershipSearchCriteria) and get a result whose Data is a "Paged Item List" of UserListItem.

(DateSearchOperator is an Enum that defines On/After/Between/etc.)

(FindMode is an Enum that defines find by UserName, Email or both.)

The PagedItemList includes the following:
  • PageNumber (int)
  • PageSize (int)
  • TotalRows (int)
  • TotalPages (int)
  • Items (List of UserListItem)
Each UserListItem includes these values:
  • UserId (usually a GUID)
  • Email (string)
  • Username (string)
  • CreationDate (DateTime)
  • LastLoginDate (DateTime)
  • LastActivityDate (DateTime)
  • IsApproved (bool)
  • IsLockedOut (bool)
ChangeUserName?
userName={username}
&newUsername={newUsername} 		HttpPost is required. Submit this request with the query string or form parameters "Username" and "NewUsername" to change a membership user's username.
ChangeEmail?
userName={username}
&email={newEmail} 		HttpPost is required. Submit this request with the query string or form parameters "Username" and "email" to change a membership user's email address.
ChangeProfile?
userName={username}
&PropertyValues={List of ProfilePropertyValue} 		HttpPost is required. Submit this request with the form parameters for "Username" and a list of profile "propertyValues" to modify a membership user's profile data. Response will provide an indication of success of failure.

Profile Properties are defined in your web.config file and are therefore somewhat dynamic from the point of view of this API. Each ProfilePropertyValue includes (as a minimum) the following:
  • Name (the name as defined in web.config
  • PropertyValue (the value of your date/string/bool/numeric data)

The ChangeProfile method uses the application's (default) Profile Provider, to determine the data type for each Name/PropertyValue and set its value.
ChangeRoles?
userName={username}
&roles={List of role names (strings)} 		HttpPost is required. Submit this request with the form parameters for "Username" and the complete list of roles for which the user should be a member. Response will provide an indication of success of failure.

The ChangeRoles method uses the application's (default) Roles Provider, to add/remove role membership based on the supplied list of roles.
ChangeComments?
userName={username}
&comments={comments (string)} 		HttpPost is required. Submit this request with the form parameters for "Username" and comments. Response will provide an indication of success of failure.

The ChangeComments method uses the application's (default) Membership Provider, to retrieve the MembershipUser, set the Comment value, then save the changes with the Provider's "UpdateUser" method.
CreateUser?
memberInfo={MemberInfo} 		HttpPost is required. Submit this request with form parameters that comprise "MemberInfo". The default Membership provider will be used to create the user and, if RoleInfo and ProfileInfo are provided, then the Roles and Profiles providers are also used to perform updates. As a minimum, the Username, Email and password are required. The response "Data" property will include MemberInfo for the newly created user (including UserId.)

MemberInfo includes this information:
  • UserId (string)
  • Username (string)
  • Email (string)
  • IsApproved (bool)
  • CreationDate (DateTime)
  • IsLockedOut (bool)
  • LastLoginDate (DateTime)
  • LastActivityDate (DateTime)
  • Password (string if enabled)
  • PasswordFormat (int)
  • PasswordSalt (string)
  • FailedPasswordAttemptCount (int)
  • FailedPasswordAnswerAttemptCount (int)
  • LastPasswordChangedDate (DateTime)
  • Question (string)
  • PasswordAnswer (string if enabled)
  • Comments (string)
  • CreationDateLabel (string, formatted date)
  • LastLoginDateLabel (string, formatted date)
  • LastActivityDateLabel (string, formatted date)
  • LastPasswordChangedDateLabel (formatted date)
  • IsApprovedLabel (string, formatted Yes/No)
  • ProfileInfo (object, see GetProfileInfo)
  • RoleInfo (object, see GetRoleInfo)
DeleteUser?
userName={username}
[&deleteRelatedData={true/false}] 		HttpPost is required. Submit this request with the form parameters for "Username" and an optional flag to delete related data. Response will provide an indication of success of failure.

The DeleteUser method uses the application's (default) Membership Provider to delete the membership user. If omitted, deleteRelatedData defaults to true.
ChangePassword?
userName={username}
&newPassword={new password (string)} 		HttpPost is required. Submit this request with the form parameters for "Username" and a new password. Response will provide an indication of success of failure.

The ChangePassword method lets Administrators set a membership user's password to a new known value. See the ResetPassword method which allows for setting a membership user's password to a new random value.
ChangePasswordAdvanced?
userName={username}
&newPassword={new password (string)}
&question={password question (string)}
&answer={passwrd answer (string)}
[&passwordFormat={passwordFormat}]
 HttpPost is required. Submit this request with the form parameters for resetting the membership user's password, password question/answer and even the method by which the password is stored (Clear/Encrypted/Hashed.) Response will provide an indication of success of failure.

The ChangePasswordAdvanced method can be used to completely reset a membership user's credentials and is useful in situations where there exists a desire to change Membership Provider's password format and existing membership users have already been created.
PasswordFormat is an enumeration defined in the System.Web.Security:
  • Clear (0) - plain text
  • Encrypted (1) - retrievable, based on machinekey
  • Hashed (2) - not retrievable
ResetPassword?
userName={username} 		HttpPost is required. Submit this request with the form parameter for "Username" to reset the user's password to a new random value. Response will provide an indication of success of failure.

The ResetPassword method uses the application's (default) Membership Provider to reset the user's password.
ToggleApproved?
userName={username} 		HttpPost is required. Submit this request with the form parameter for "Username" to toggle the user's approval status. Response will provide an indication of success of failure.

The membership user's approval status can be used to allow or disallow the user from logging into the application. A common practice on self service membership systems is to initially default the approval status to false and require approval by an Administrator.
Unlock?
userName={username} 		HttpPost is required. Submit this request with the form parameter for "Username" to unlock a membership user who has become locked out as a result of excessive invalid password attempts. Response will provide an indication of success of failure.

Depending on the membership provider's configuration, a membership user may become locked out if numerous invalid password or password recovery attempts occur within a defined period of time.
Role Management methods
RoleSummary?
[count={# records to return (int)}] 		Returns a response whose "Data" property includes a list of roles and the number of users in each as well as an indication of the total number of roles and whether roles are enabled. Specifically, the data is a RolesSummary that includes these values:
  • Roles (List of RoleMemberCount)
  • RolesEnabled (bool)
  • TotalRoles (int)

Each listed role is a RoleMemberCount that includes these values:
  • RoleName - (string)
  • Members - Count (int)

The optional count parameter defines the number of roles that will be returned (default is 5) and the information is obtained by calling methods in the application's default Roles Provider.
GetAllRoles Returns a response whose "Data" property includes a list of roles as well as an indication of whether roles are enabled. Specifically, the data is a RoleInfo object that includes these values:
  • Roles (List of Role)
  • RolesEnabled (bool)

Each listed Role includes these values:
  • RoleName - (string)
  • Description - (string)
GetRoleMembers?
[Rolename={name of role (string)}]
[&FindMode={FindMode}]
[&IncludeNonMembers={true/false}] 		Get or Post parameters (shown at left and which are interpreted as RolesSearchCriteria) and get a result whose Data is a "Paged Item List" of RoleMember information.
FindMode is an Enum that defines find by UserName (0), Email(1) or both(2).

The PagedItemList includes the following:
  • PageNumber (int)
  • PageSize (int)
  • TotalRows (int)
  • TotalPages (int)
  • Items (List of RoleMember)
Each RoleMember includes these values:
  • Username (string)
  • Rolename (string)
  • Email (string)
  • IsInRole (bool)
CreateRole?
roleName={name of role (string)}
[&description={optional (string)}] 		HttpPost is required. Submit this request with the form parameter for a new role name to create a new membership role. Response will provide an indication of success of failure.
UpdateRole?
roleName={name of role (string)}
&description={description (string)} 		HttpPost is required. Submit this request with form parameters for role name and description set the description for a role. Response will provide an indication of success of failure.
DeleteRole?
roleName={name of role (string)} 		HttpPost is required. Submit this request with a form parameter indicating the name of a membership role to be deleted. This method uses the the default Roles Provider's DeleteRole method to delete the role. Response will provide an indication of success of failure.
UpdateRoleMembership?
roleName={name of role (string)}
&userName={name of user (string)}
&isInRole={true/false (bool)} 		HttpPost is required. Submit this request with form parameters including the role name, membership user name and a boolean to associate or dissociate the membership user and role. Response will provide an indication of success of failure.
Dashboard and reporting methods
GetAllUserRoles?
userName={username} 		Returns a response whose "Data" property includes a list of all defined roles and an indication of whether the user is in each role. Each item is a UserInRole object and contains the following:
  • RoleName - name of role (string)
  • IsInRole - true/false
LatestLogins?
[count={# records to return (int)}] 		Returns a response whose "Data" property includes a list with the last users to log into the application. The count is optional and defaults to 5. Each list item is a UserListItem and includes these values:
  • UserId (usually a GUID)
  • Email (string)
  • Username (string)
  • CreationDate (DateTime)
  • LastLoginDate (DateTime)
  • LastActivityDate (DateTime)
  • IsApproved (bool)
  • IsLockedOut (bool)
NewestMembers?
[count={# records to return (int)}] 		Returns a response whose "Data" property includes a list with the newest membership users. The count is optional and defaults to 5. Each list item is a UserListItem and includes these values:
  • UserId (usually a GUID)
  • Email (string)
  • Username (string)
  • CreationDate (DateTime)
  • LastLoginDate (DateTime)
  • LastActivityDate (DateTime)
  • IsApproved (bool)
  • IsLockedOut (bool)
MembershipSummary Returns a response whose "Data" property includes information summarizing high-level information about the membership system. The returned MembershipSummary includes these values:
  • StatusDate (DateTime)
  • TotalMembers (int)
  • OnlineMembers (int)
  • UnapprovedMembers (int)
  • LockedOutMembers (int)
  • FirstCreateDate (DateTime)

The information is obtained through the use of methods on the application's default Membership Provider.
MembershipAgingSummary Returns a response whose "Data" property lists the number of users that were created each month. Each list item is a PeriodCount that includes these values:
  • Period (string "yyyyMM")
  • Count (int)

The information is useful for showing a trend of new membership users over a period of time.
MembershipDailyEnrollmentSummary Returns a response whose "Data" property lists the number of users that were created each day since the first of the prior month. Each list item is a DailyCount that includes these values:
  • Year - (int)
  • Month - (int)
  • Day - Day of month (int)
  • Count - (double)
  • CumulativeCount - Cum for period (double)

The information is useful for showing the number of users (daily and cumulative) who have signed up in a recent period of time.
MembershipCumulativeMonthlyEnrollmentSummary Returns a response whose "Data" property is a PagedItemList that includes the following:
  • PageNumber (int)
  • PageSize (int)
  • TotalRows (int)
  • TotalPages (int)
  • Items (List of DailyCount)

Each list item is a DailyCount that includes these values:
  • Year - (int)
  • Month - (int)
  • Count - (double)
  • CumulativeCount - Cumulative count
The information provides the number of new users each month and includes a cumulative number of users over a period of time. The data commences on the first date on which a user record is created.
LastLoggedInSummary Returns a response whose "Data" property indicates the number of users whose last log in was in each of the preceding months. Each list item is a PeriodCount that includes these values:
  • Period (string "yyyyMM")
  • Count (int)

The information is an indication of the last login date and not of the number of logins for each month. As such, it is useful for identifying decreasing usage rates in the application. An ideal situation would be one where preceding months have very small counts.
Authentication methods
Login?
userName={name of user (string)}
password={password (string)} 		HttpPost is required. Submit this request with form parameters for username and password to log in. The underlying Membership Provider is used to validate the credentials and an Asp.Net Forms Authentication token is used to manage identity.
If the user provides proper credentials but is not a member of one of the roles listed in the Dot Net Dash "Roles" Property, then the user will be logged in but the response will contain an error message indicating "Unauthorized". A user must be both authenticated and authorized in order to issue requests to the REST API.
Logout HttpPost is required. Submit this request to log out. The API simply calls the FormsAuthentication.SignOut() method.
Miscellaneous methods
GetAuthenticatedUser HttpPost is required. Submit this request to return information about the currently logged-in user. This is a useful tool for use when performing client-side debugging as it returns the following information:
  • Username (string)
  • Roles (role names for user)
  • IsAuthenticated (bool)
  • AuthenticationType (string)
  • IsAuthorized (bool)

IsAuthorized returns true if the current user is a member of one of the roles listed in the Dot Net Dash "Roles" property.
Ping Returns the current server date/time. Useful for testing whether a controller route is properly registered.
About Returns information about the Dot Net Dash API including whether the default membership, role and profile providers support the functionality required by the Silverlight client application.