Child pages
  • GetFile
Skip to end of metadata
Go to start of metadata

Description

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

 

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 behavior 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 required file.


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 or device 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 id parameter is not sent.

No*

 

 

apsdb.id

The unique identifier of the user or the device whose 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 or a device 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.

A value of “false” will show the file, and a value of “true” will download it.

Note that setting the value to false is only effective in the case you are sending the request from a browser or an HTTP client and if your device is configured to open the type of the file. In the other cases, notably when you are invoking the GetFile API from a server-side script, e.g. PHP, the file can only be downloaded (i.e. setContentDisposition == true, also check Apstrata's SDKs for more information)

No

true


true
false

apsdb.runAs

It allows the owner to run a service as one of his own users and devices.

No

 

Valid identifier

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 GenerateToken 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

DOCUMENT_NOT_FOUND

Document with key [documentKey] and version: [version ]: was not found

400

FILE_DOWNLOAD_TIME_EXCEEDED

Maximum download time exceeded

400

FILE_NOT_FOUND

Could not read the requested file [fileName]

400

INTERNAL_ERROR

 

400

INVALID_REQUEST

apsdb.login cannot be used in conjunction with apsdb.documentKey

apsdb.login cannot be used in conjunction with apsdb.id

apsdb.login cannot be used in conjunction with apsdb.store

apsdb.id cannot be used in conjunction with apsdb.documentKey

400

 INVALID_PARAMETER_VALUE

Incorrect value for parameter apsdb.versionNumber

400

 INVALID_DEVICE

The device [Identifier] does not exist.

400

 INVALID_USER

The user [Identifier] does not exist.

400

INVALID_DOCUMENT_KEY

 

400

MAX_RESPONSE_SIZE

The requested file [fileLength] is larger than the maximum allowed response size of [maxResponseSize]

400

NOT_A_FILE

The requested field [fieldName] is not a file attachment

400

PARAMETER_REQUIRED

Either the [login] or the [apsdb.documentKey] or the[apsdb.id] parameter must be specified in GetFile

400

PERMISSION_DENIED

 

 400

STORE_NOT_FOUND

The store was not found

404

 

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"
    }
}} 
  • No labels