pages/{pageid}/allowed (POST)

Overview

Filter a list of user ids based on access to the page

Uri Parameters

Name Type Description
pageid int integer page ID

Query Parameters

Name Type Description
filterdisabled bool? DEPRECATED: Will always filter disabled users, regardless of permissions
permissions string? A comma separated list of permissions that must be satisfied (e.g read, etc.). Defaults to read, if not provided

Return Codes

Name Value Description
OK 200 The request completed successfully
Bad Request 400 Invalid input parameter or request body
Forbidden 403 Read access to the page is required
Not Found 404 Requested page could not be found

Message Format

Input:

List of all users to run feature against:

<users>
	<user id="{id}"/>
        <user id="{id}"/>        
        ...
</users>

Output:

List of all users with allowed permissions as specified in the query parameter:

<users>
	<user id="{id}"/>
        <user id="{id}"/>
        ...
</users>

Implementation Notes

The feature takes in as input a list of users and outputs a filtered user list whose members have a page permission that matches one or more of the permissions given in the query parameter.

Curl Code Sample: Check User Access to Page

The following command returns a sublist of users with defined permissions to a page (page ID = 1). The users are listed in "users.xml". The permissions are appended to the "permissions parameter":

Sample Code

curl -u username:password -H "Content-Type: application/xml" -d @uesrs.xml -i http://mindtouch.address/@api/deki/pages/1/allowed?permissions="NONE LOGIN BROWSE READ ..."

Implementation notes 

Permissions

Sending the above command with a NONE permission parameters does not yield a response of interest. This is that permissions matches all users, and thus will simply return the list of users sent in the request. To receive a useful response, such as what users have the permissions to read, update, set permissions, and so on, a "permissions" parameter is appended to the end of the path.
 
For example, the following command will check which users have READ, UPDATE, and LOGIN permissions for a page (page ID = 2):
 
curl -u username:password -H "Content-Type: application/xml" -d @users.xml -i http://mindtouch.address/@api/deki/pages/2/allowed?permissions="READ UPDATE LOGIN"

 

The response will contain a list of users who have one or more of those permissions for the specific page.

Permission Enumeration

 

NONE 0
LOGIN 1
BROWSE 2
READ 4
SUBSCRIBE 8
UPDATE 16
CREATE 32
DELETE 256
CHANGEPERMISSION 1024
CONTROLPANEL 2048
UNSAFECONTENT 4096
ADMIN

0x8000000000000000L

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.
-d @file
Specifies a POST request and file to send.
-H
Replaces or appends an HTTP header. The "Content-Type" header specifies the MIME type of the value attached to the property. In this case, use application/xml since the document being passed is of type XML.
-i
Includes the HTTP response header in the output. Useful for debugging.

Example

A page (Page ID = 571) has been set to private. A user (User ID = 4) has been given full Contributor role permissions to the page. We want to verify what users from a list have the READ, UPDATE, and CREATE permissions for the specific page.

usersallowed.xml

Content-Type: text/plain

<users>
	<user id="1"/> <!-- admin userID, should be returned -->
	<user id="88"/> <!-- random users -->
	<user id="89"/>
	<user id="4"/> <!-- user with permissions to the page -->
</users>

Sample Code

curl -u admin:password -H "Content-Type: application/xml" -d @usersallowed.xml -i http://192.168.59.128/@api/deki/pages/571/allowed?permissions="READ UPDATE CREATE"

HTTP Response Headers

HTTP/1.1 200 OK
Date: Mon, 25 Jan 2010 23:19:44 GMT
Server: Dream-HTTPAPI/2.0.0.17629 Microsoft-HTTPAPI/2.0
Content-Length: 45
Content-Type: application/xml; charset=utf-8
X-Data-Stats: request-time-ms=65; mysql-queries=4; mysql-time-ms=63;
X-Deki-Site: id="default"
Via: 1.0 dekiwiki
Connection: close

HTTP Response Body

Content-Type: application/xml

<users>
    <user id="1" />
    <user id="4" />
</users>