Overview
Perform changes on multiple user properties
- REST Method: PUT
- Method Access: public
Uri Parameters
Name | Type | Description |
userid | string | either an integer user ID, "current", or "=" followed by a double uri-encoded user name |
Query Parameters
Name | Type | Description |
authenticate | bool? | Force authentication for request (default: false) |
redirects | int? | If zero, do not follow page redirects. |
Return Codes
Name | Value | Description |
OK | 200 | The request completed successfully |
Bad Request | 400 | Invalid input parameter or request body |
Forbidden | 403 | ADMIN access is required to access other user's properties |
Not Found | 404 | Requested user could not be found |
Message Format
Input is a list of property xml blocks. Only text values are allowed to be modified via this feature. To modify a non-text property value, use PUT: users/{userid}/properties/{key} instead. Properties are deleted if no contents node is provided. An etag is not required for deleting properties.
2 | < property name = "{text}" etag = "{text}" > |
3 | < contents type = "{text}" >{text}</ contents > |
4 | < change-description >{text}</ change-description > |
6 | < property name = "{text}" /> |
Response is a list of the standard property xml blocks as well as any error blocks.
01 | < properties count = "{int}" href = "{uri}" > |
02 | < property name = "{text}" href = "{uri}" etag = "{text}" > |
03 | < contents type = "{text}" href = "{uri}" >{text}</ contents > |
04 | < date.modified >{date}</ date.modified > |
05 | < user.modified id = "{int}" href = "{uri}" > |
07 | < username >{text}</ username > |
09 | < change-description >{text}</ change-description > |
11 | < property name = "{text}" > |
14 | < status >{int}</ status > |
16 | < message >{text}</ message > |
Implementation Notes
- The response XML will contain the contents text only for text based mimetypes with values less than 2048 chars in length. Otherwise the contents is available at the URI pointed to by property/contents/@href.
- A user may only read and write their own properties. Admins can read/write anyones users properties.
C# Sample: Code Samples
Authentication is performed and a property for the current user is created named "myprop". Using the batch property update feature, "myprop" is updated with a new value with the current value's etag. A non existent property "propertyToDelete" is attempted to be deleted by not specifying a new content value.
Sample Code
02 | p.At( "users" , "authenticate" ).WithCredentials( "sysop" , "password" ).Get(); |
04 | XDoc myPropResponse = p.At( "users" , "current" , "properties" ) |
05 | .WithHeader( "Slug" , "myprop" ) |
06 | .Post(DreamMessage.Ok(MimeType.TEXT_UTF8, "initial value" )).AsDocument(); |
08 | XDoc body = new XDoc( "properties" ); |
09 | body.Start( "property" ).Attr( "name" , "myprop" ).Attr( "etag" , myPropResponse[ "/property/@etag" ].AsText) |
10 | .Start( "contents" ).Attr( "type" , "text/plain" ).Value( "new value for property" ).End() |
11 | .Elem( "description" , "description of change" ) |
13 | body.Start( "property" ).Attr( "name" , "propertyToDelete" ).End(); |
15 | XDoc response = p.At( "users" , "current" , "properties" ) |
16 | .Put(body).AsDocument(); |
Sample Response from executing Code
04 | < date.modified >2009-03-20T23:52:50Z</ date.modified > |
07 | < username >Sysop</ username > |
09 | < change-description >description of change</ change-description > |
12 | < property name = "propertyToDelete" > |
16 | < title >Bad Request</ title > |
17 | < message >The property 'propertyToDelete' does not exist and cannot be deleted.</ message > |
Implementation notes
Add notes about requirements or config values.
Curl Sample: Code Samples
The following command applies the properties listed in "properties.xml" to a user with user ID = 1.
Implementation notes
curl flags
- -u
- Basic HTTP authentication. Sends a username and password to server so it can verify whether a user is of privilege to perform specific operation.
- -H
- Adds a header or modifies an existing one. In this case, since an xml document is being sent, the content type must be set to "application/xml". The server will not accept the request otherwise.
- -T file
- Specifies the .xml file that contains the user property data.
- -i
- Includes the HTTP response header in the output. Useful for debugging.
Permissions
ADMIN permission is required to execute above command. Otherwise, a 403 HTTP response (Forbidden) will be returned.
Example
Batman happens to be an Expert user. We want to make changes to his properties. The following XML document adds a couple properties and removes the "alterego" property added in this example. Batman's user ID = 4.
batman.xml
Content-Type: application/xml
05 | < property name = "location" > |
06 | < contents type = "text/plain" >Gotham</ contents > |
08 | < property name = "transportation" > |
09 | < contents type = "text/plain" >Batmobile</ contents > |
14 | < property name = "alterego" /> |
HTTP Response Headers
HTTP/1.1 200 OK
Date: Tue, 12 Jan 2010 23:51:20 GMT
Server: Dream-HTTPAPI/1.7.2.17433
X-Deki-Site: id="default"
Content-Type: application/xml; charset=utf-8
Content-Length: 2444
Via: 1.1 dekiwiki
HTTP Response Body
Content-Type: application/xml
05 | < date.modified >2010-01-12T23:51:20Z</ date.modified > |
08 | < username >Admin</ username > |
09 | < email >melder@mindtouch.com</ email > |
10 | < hash.email >637b79dca5c8ebdc4347bccca42d3487</ hash.email > |
17 | < date.modified >2010-01-12T23:51:20Z</ date.modified > |
20 | < username >Admin</ username > |
21 | < email >melder@mindtouch.com</ email > |
22 | < hash.email >637b79dca5c8ebdc4347bccca42d3487</ hash.email > |
29 | < date.modified >2010-01-12T23:51:20Z</ date.modified > |
32 | < username >Admin</ username > |
33 | < email >melder@mindtouch.com</ email > |
34 | < hash.email >637b79dca5c8ebdc4347bccca42d3487</ hash.email > |
39 | < username >Admin</ username > |
40 | < email >melder@mindtouch.com</ email > |
41 | < hash.email >637b79dca5c8ebdc4347bccca42d3487</ hash.email > |
44 | < date.deleted >2010-01-12T23:51:20Z</ date.deleted > |