pages/{pageid}/files/{filename} (GET)
Overview
Retrieve file attachment content
- REST Method: GET
- Method Access: public
Uri Parameters
Name | Type | Description |
fileid | int | identifies a file by ID |
filename | string | Double uri-encoded file name. Should be prefixed with "=" if it does not have an extension. |
pageid | string | either an integer page ID, "home", or "=" followed by a double uri-encoded page title |
Query Parameters
Name | Type | Description |
authenticate | bool? | Force authentication for request (default: false) |
redirects | int? | If zero, do not follow page redirects (only applies when {pageid} is present). |
includeDeleted | bool | When fileid is an integer ID, and this parameter is set to true, we will even return the file info if it was deleted at some point |
revision | string? | File revision to retrieve. 'head' by default will retrieve latest revision. positive integer will retrieve specific revision |
size | {original, thumb, webview, bestfit, custom}? | Return a resized image from one of the preset cached sizes. Use 'thumb' or 'webview' to return a smaller scaled image. Use 'bestfit' along with height/width to return one of the known sizes being at least the size given. Default: original |
format | {jpg, png, bmp, gif}? | Convert output to given type. Default is to use original type. |
ratio | {fixed, var}? | Fixed preserves aspect ratio by applying height and width as bounding maximums rather than absolute values. Variable will use the width and height given. Default: fixed |
width | int? | Width of the image |
height | int? | Height of the image |
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 file could not be found |
Not Implemented | 501 | Requested operation is not currently supported |
Message Format
None
Implementation Notes
Use of the format, ratio, width/height, and size parameters requires the file to be an image.
The Content-Disposition, Content-Length, and Content-Type headers provide information about the retrieved file.
C# Code Sample: Retrieve a Page File
The following code example retrieves the file called "myfile.jpg" from the home page using a best fit of 100x100. The result is saved in the caller's temporary directory:
Sample Code
Plug p = Plug.New("http://deki-hayes/@api/deki"); p.At("users", "authenticate").WithCredentials("admin", "password").Get(); DreamMessage msg = p.At("pages", "home", "files", "=myfile%252ejpg").With("size", "bestfit").With("width", 100).With("height", 100).Get(); using (FileStream fs = System.IO.File.OpenWrite(Path.GetTempPath() + msg.ContentDisposition.FileName)) { byte[] fileData = msg.AsBytes(); fs.Write(fileData, 0, fileData.Length); }
Implementation notes
Add notes about requirements or config values
Curl Code Sample: Retrieve a Page File
The following command retrieves file "foo" from page "bar":
Sample Code
curl -u username:password -i http://mindtouch.address/@api/deki/pages/=bar/files/=foo
Implementation notes
curl flags
- -u
- Provides external user authentication. Note that if anonymous access is available and authentication is not forced, this flag may be omitted.
- -i
- Outputs the HTTP response headers. Useful for debugging.
Response
- Note that a file, not an XML document, is returned. So if an image or any non-text file is requested, and the output is not directed somewhere, a bunch of junk will be printed in console.
Pages
- To view a list of pages, follow the instructions here.