pages/{pageid}/allowed (POST)
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>