pages/{pageid}/allowed (POST)

Last updated
Save as PDF

Overview

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

REST Method: POST
Method Access: public

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>