Description

The GetFile API allows a developer to download a specific file from the specified document and to return it as a binary stream.

What is a File?

In apstrata, a File is any digital content or asset that gets attached to a Document. More than one File can be attached to a single Document, or even to a single field within a single Document. One of the Document fields can be a File, with associated read and write ACLs.

Hence, a developer can easily upload or download Files as part of the developed application.

For more specific details, please check the SaveDocument API for uploading files or the GetFile API for downloading files.

The default response behaviour is to specify the response header "Content-Disposition: attachment; filename=" which will force most user agents to download the file. To eliminate the Content-Disposition response header, set the parameter apsdb.setContentDisposition=false. Note that the file name must be specified using the apsdb.fileName parameter, even if the document field contains only a single file. In order to get a file from a document with a default schema, the field name should be “apsdb_attachments”.

ACL

The user cannot call GetFile on a field if there is no read ACL for this user on this field.

Specific Request Parameters

(Refer to Common Request Parameters)

Name	Description	Required	Default	Possible Values
apsdb.fileName	The name of the file needed	Yes
apsdb.store	The store name from which you are getting your file. This parameter should not be sent if file is attached to a user document and consequently, the apsdb.documentKey parameter is not sent.	No	DefaultStore
apsdb.documentKey	The universally unique document identifier. This parameter must be sent if and only if the login parameter is not sent.	No*
login	The unique login of the user whose user document contains the file to download. This parameter must be sent if and only if the apsdb.documentKey parameter is not sent, meaning that the file is attached to a user document, not a store document.	No*
apsdb.fieldName	The name of the field of type file whose file is to be streamed back.	Yes
apsdb.setContentDisposition	Specifies whether or not to send the file to be downloaded or not. A value of “false” will show the file, and a value of “true” will download it	No	true	true false
apsdb.runAs	It allows the owner to run a service as one of his own users. The possible values are any of the usernames.	No
apsdb.versionNumber	Indicates a specific version of the specified document. If not specified, then the latest version of the document will be used.	No		numeric
apsdb.authToken	This parameter is used to sign the request with a token that was initially obtained by calling VerifyCredentails API. For more details on signing requests, please refer to the page entitled Authentication .	No

* Note that one of these parameters must be sent in the request, but not both.

Specific Response Elements

This apstrata database action will stream the file to the requester.

Specific Logical Errors

(Refer to Common Logical Error Codes)

Error	Message	Status Code
STORE_NOT_FOUND	The store was not found	404
DOCUMENT_NOT_FOUND	The document with “document_key” “[documentKey]” could not be found for update	404
PARAMETER_REQUIRED		400
NOT_A_FILE	Field is not a file	400
MAX_RESPONSE_SIZE	The max response size has been exceeded	409
NOT_A_FILE	Field is not a file	400
FILE_DOWNLOAD_TIME_EXCEEDED	Maximum download time exceeded	400

Examples

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/ [authenticationkey]/GetFile?apsws.time=[timestamp]&apsws.authSig=[signature]

POST parameters:

apsdb.store=ClevelandMain
apsdb.documentKey=doc_key_1
apsdb.fieldName=file1
apsdb.fileName=picture.jpg

Sample XML Response

Success XML: A response with the file name in the header and the requested file as a binary stream.

Sample response header:

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=05ADE25A089CE99548229A62C925C6F5; Path=/autoforms
Accept-Ranges: bytes
ETag: 1237199907078
Last-Modified: Mon, 16 Mar 2009 10:38:27 GMT
Expires: Thu, 01 Jan 1970 00:00:00 GMT
cache-control: must-revalidate
content-disposition: attachment; filename="Sunset.jpg"
Size: 71189
Content-Type: image/jpeg
Content-Length: 71189
Date: Mon, 16 Mar 2009 12:21:23 GMT

Failure XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>failure</status>
        <errorCode>[errorCode]</errorCode>
        <errorDetail>[failMsg]</errorDetail>
    </metadata>
</response>

Sample JSON Response

Failure:

{"response": {
    "metadata": {
        "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "status": "failure",
        "errorCode": "ERROR_CODE",
        "errorDetail": "ERROR_DETAIL"
    }
}}

Child pages

GetFile

Description

ACL

Specific Request Parameters

Specific Response Elements

Specific Logical Errors

Examples