Files

You can use Kinvey to store and retrieve binary files of size up to 5TB. Files can be of any format.

The files are automatically enabled for download using a Content Delivery Network (CDN) for massive scale and performance.

Kinvey does not directly serve or accept files. Instead, the Kinvey Files API works by providing a short-lived URL to a third-party cloud storage service from which file(s) can be uploaded or downloaded. Currently, the third-party service used is Google Cloud Storage.

You would typically use the Files API to upload and download:

images
video files
other application-specific files.

Uploading

Uploading to Kinvey is a two-step process. First, you must send a PUT or POST request to Kinvey. You can use this initial request to store the filename, ACLs, and any other metadata having to do with the file you wish to upload. Then, you will upload your file directly to Google Cloud Storage using a URL provided by Kinvey.

Making the requests

First, send a POST request to /blob/:appKey. Alternatively, you may send a PUT request to /blob/:appKey/:fileId. Your request body may optionally contain a _filename, ACLs and other metadata. If a filename is not specified, a UUID will be used to populate the _filename property.

POST /blob/:appKey HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [user credentials]

{
    "_filename": "myFilename.png",
    "_acl": { ... },
    "myProperty": "some metadata",
    "someOtherProperty": "some more metadata"
}

HTTP/1.1 201 OK
Content-Type: application/json

{
    "_id": "<uuid>",
    "_filename": "myFilename.png",
    "_acl": { ... },
    "myProperty": "some metadata",
    "someOtherProperty": "some more metadata",
    "_uploadURL": <Google Cloud Storage upload URL>,
    "_expiresAt": "2013-06-18T23:07:23.394Z"
    "_requiredHeaders": {
        "x-goog-acl": "private"
    }
}

When using custom values for _id, you should avoid values that are exactly 12 or 24 symbols in length. Such values are automatically converted to BSON ObjectID and are not stored as strings in the database, which can interfere with querying and other operations.

To ensure that no items with 12 or 24 symbols long _id are stored in the collection, you can create a pre-save hook that either prevents saving such items, or appends an additional symbol (for example, underscore) to the _id:

if (_id.length === 12 || _id.length === 24) {
  _id += "_";
}

The response from Kinvey will contain the file's _id and _filename, any other metadata that you submitted, as well as an _uploadURL property containing a URL to which you will upload your file and an _expiresAt property containing the time at which the upload link will expire. The response may also contain a _requiredHeaders property, which is an object containing key-value pairs of headers and their values. If this property exists as part of the response, you must include all headers specified in it, set to the respective values, when uploading your file to the _uploadURL.

Next, extract the _uploadURL from the response body and upload the file by making a PUT request to this URL. Aside from the required headers which are included in the _requiredHeaders property, you can include a non-mandatory Content-Type header. If you plan to specify a content type, see Specifying a Content-Type.

PUT <Google Cloud Storage upload URL> HTTP/1.1
Content-Length: <content length>

<raw content of the file to be uploaded>

In the request body, pass the file content in raw form.

For more details on uploading files to Google Cloud Storage, refer to the Google Cloud Storage PUT Object documentation.

_uploadURL is a temporary URL that will expire 30 seconds after your PUT or POST request to Kinvey. While you must begin your file upload within that time limit, the upload itself may take longer.

Specifying a content type

If you plan to include a Content-Type header when uploading your file to Google Cloud Storage, you must first include its value in the X-Kinvey-Content-Type header in your request to Kinvey.

Example Kinvey request:

POST /blob/:appKey HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [user credentials]
X-Kinvey-Content-Type: "image/png"

{
    "_filename": "myFilename.png",
    "_acl": { ... },
    "myProperty": "some metadata",
    "someOtherProperty": "some more metadata"
}

HTTP/1.1 201 OK
Content-Type: application/json

{
    "_id": <uuid>,
    "_filename": "myFilename.png",
    "_acl": { ... },
    "myProperty": "some metadata",
    "someOtherProperty": "some more metadata",
    "_uploadURL": <Google Cloud Storage upload URL>,
    "_expiresAt": "2013-06-18T23:07:23.394Z"
}

When you are then making the request to Google Cloud Storage, ensure that you set the Content-Type header to the same type. The requests body must still include the file content in raw form.

PUT <Google Cloud Storage upload URL> HTTP/1.1
Content-Type: "image/png"

<raw content of the file to be uploaded>

Recommended properties

The Files section of the Kinvey Console is capable of displaying the size and mime type of your files. However, in order to display this information for your files, you will need to store two extra properties with each one: size (in bytes) and mimeType.

POST /blob/:appKey HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [user credentials]

{
    "_filename": "myFilename.png",
    "_acl": { ... },
    "size": 46530,
    "mimeType": "image/png"
}

Note that the JavaScript, iOS and Android libraries automatically add these properties when uploading files. These properties will also be automatically added when uploading a file through the Console.

Creating publicly-readable files

By default, files uploaded to Google Cloud Storage through the Kinvey File API are private. This means that every time you wish to download a file, you must first request it via a GET request to Kinvey, which will generate a signed URL that allows download access only for a limited time.

However, using the File API, you may optionally create a publicly-readable file. The download link to this file will be a regular non-signed URL, which will not expire until you delete the file through Kinvey or change the file's status to be private again. To create a publicly-readable file, set the _public flag to true when PUTing or POSTing the file's metadata to Kinvey

POST /blob/:appKey HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [user credentials]

{
    "_id": <uuid>,
    "_filename": "myFilename.png",
    "_public": true
}

Once you have uploaded or updated a file in this way, follow the normal instructions to download the file. The _downloadURL property will contain a non-signed, publicly-accessible URL, which will not expire until you delete the file through Kinvey.

If you wish to make the file private again, repeat this process, but set _public to false.

Required headers for Kinvey (/blob/:appKey) request

Authorization

Required headers for actual upload to Google Cloud Storage

Any headers specified in _requiredHeaders

Downloading

Downloading from Kinvey is again a two-step process. First, you must send a GET request to Kinvey in order to retrieve the Google Cloud Storage URL associated with your file, as well as any metadata you stored when creating the file. Then, you will download your file directly from Google Cloud Storage.

First, send a GET request to /blob/:appKey or /blob/:appKey/:fileId. The file API supports complex queries; for more information, please refer to the querying guide.

GET /blob/:appKey/:fileId HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]

The response from Kinvey will contain the file _id and _filename, any other metadata that you submitted, as well as an _downloadURL property containing a URL from which you will download your file, and if the file is not public, an _expiresAt property containing the time at which the download link will expire:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "_id": "<uuid>",
    "_filename": "myFilename.png",
    "_acl": { ... },
    "myProperty": "some metadata",
    "someOtherProperty": "some more metadata",
    "_downloadURL": <Google Cloud Storage download URL>,
    "_expiresAt": "2013-06-18T23:07:23.394Z"
}

Next, extract the _downloadURL from the response body and download the file by making a GET request to this URL. Since the necessary authorization information is already embedded in the URL, no authorization header is required. For more details, please refer to the Google Cloud Storage GET Object documentation.

_downloadURL is a temporary URL that will expire one hour after your GET request to Kinvey. While you must begin your file download within that time limit, the download itself may take longer.

Specifying a custom expiration time

If you require the temporary download URL to last longer (or shorter) than one hour, you may optionally specify a custom expiration time (in seconds) using the ttl_in_seconds query parameter.

GET /blob/:appKey/:fileId?ttl_in_seconds=3600 HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]

If you would like to upload a publicly-readable file that never expires, please refer to the creating publicly-readable files section.

Required headers for Kinvey (/blob/:appKey) request

Authorization

Deleting

In contrast to the other two operations, deleting a file using the Kinvey File API is done in a single step. In order to delete a file, simply send a DELETE request to /blob/:appKey/:fileId.

DEL /blob/:appKey/:fileId HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]

If the deletion operation was successful, Kinvey will respond with a 200, and the number of files that have been deleted.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 1
}

Required headers

Authorization

Linking files to entities in collections

Many common uses for files involve associating them with entities that reside in collections. In order to make this experience as easy as possible, entities in collections may contain KinveyFile references. These references will be automatically resolved when the entity that contains them is retrieved through the Data Store API.

Creating a KinveyFile reference

A reference to a file stored using Kinvey, or a KinveyFile reference, is simply a JSON object with a _type of KinveyFile and an _id containing the ID of a file in Kinvey (as created through the File API).

To store a KinveyFile reference, create or update an entity in any collection with such a property. For example:

PUT /appdata/:appKey/:collectionName/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
Content-Type: application/json

{
    "dogName": "Bob",
    "furColor": "brown with black spots",
    "pawPrintPicture": {
        "_type": "KinveyFile",
        "_id": "325620e4-93dd-4a26-9f84-8a5e62c0db11"
    }
}

Please note that only two properties are allowed in a KinveyFile reference: _type and _id. If you attempt to save any additional properties as part of the KinveyFile JSON object, these properties will be ignored by Kinvey and not saved. Any additional properties that you wish to assiciate with the file should be a part of the file itself, and set through the File API.

A KinveyFile is only a reference to a file stored on Kinvey. You are responsible for uploading the file itself using the File API. It is good practice to first upload the file, and only then create the KinveyFile reference.

Downloading using a KinveyFile reference

When querying any collection through the Data Store API, Kinvey will resolve any KinveyFile reference and provide you with a _downloadURL.

GET /appdata/:appKey/:collectionName/:id HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]

HTTP/1.1 200 OK
Content-Type: application/json

{
    "_id": "3f583e9f-d064-4a25-a953-6cf0a3dc2ff1",
    "_acl": {...},
    "dogName": "Bob",
    "furColor": "brown with black spots",
    "pawPrintPicture": {
        "_type": "KinveyFile",        
        "_id": "325620e4-93dd-4a26-9f84-8a5e62c0db11",
        "_filename": "bobsPawPrint.png",
        "_acl": { ... },
        "_downloadURL": <Google Cloud Storage download URL>,
        "_expiresAt": "2013-06-18T23:07:23.394Z"
    }
}

You will then need to download the file directly from Google Cloud Storage by making a GET request to the _downloadURL, as explained above.

_downloadURL is a temporary URL that will expire one hour after your GET request to Kinvey. While you must begin your file download within that time limit, the download itself may take longer.

Specifying a custom expiration time

If you require the temporary download URL to last longer (or shorter) than one hour, you may optionally specify a custom expiration time (in seconds) using the kinveyfile_ttl query parameter.

GET /appdata/:appKey/:collectionName/:id?kinveyfile_ttl=3600 HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]

If you would like to upload a publicly-readable file that never expires, please refer to the uploading publicly-readable files section.

Securely communicating with GCS

By default, the upload and download URLs generated by Kinvey use the http protocol to communicate with Google Cloud Storage. However, you may optionally request an https URL using the tls query parameter.

While the following example uses POST, the same query parameter can also be applied to PUT or GET requests.

POST /blob/:appKey?tls=true HTTP/1.1
Host: baas.kinvey.com
Content-Type: application/json
Authorization: [user credentials]

{
    "_filename": "myFilename.png",
    "_acl": { ... },
    "myProperty": "some metadata",
    "someOtherProperty": "some more metadata"
}

When using KinveyFiles

Secure communication is available as a query parameter when retrieving KinveyFile references through the Data Store API, as well. To use https instead of http, set the kinveyfile_tls parameter to true.

Business Logic

You may create Business Logic code which will execute before or after each File API v3 route. To do so, simply add hooks to the _blob collection just like any other data collection. For more information on Business Logic, refer to the Business Logic guide.

Please note that Business Logic is only supported for File API version 3 routes. If you attempt to access a File API version 2 route that includes Business Logic, your request will fail.

Comprehensive reference

Properties

While you may include any number of custom metadata properties when saving your file, Kinvey uses certain properties to maintain its own metadata. This section contains a comprehensive list of all special Kinvey attributes that may be part of a file.

Property	Included when	Short description
_id	Always	A unique identifier
_filename	Always	A filename
_acl	Always	The file's Access Control List
_kmd	Always	Kinvey metadata, including `lmt` and `ect`
_public	Always	If set to `true`, the file is publicly accessible through an unsigned URL. Defaults to `false`
_downloadURL	Downloading	A link to GET the file
_uploadURL	Uploading	A link to PUT the file
_expiresAt	Downloading or uploading	The time at which the link will expire. Will not be included if the file's `_public` attribute is set to `true`
_requiredHeaders	Uploading	An object containing key-value pairs of headers and their values. If this property exists and is not empty, you must include these headers set to the correct values when uploading the file to Google Cloud Storage.

Special supported properties

The following properties, while optional, will allow the Kinvey Console to display more information about the file if you specify them as part of the file metadata.

Property	Short description
mimeType	The mime type of the file (e.g. text/plain, image/png, etc)
size	The size of the file, in bytes

Headers

Header	Short description
X-Kinvey-Content-Type	Must be specified when making a POST or PUT request through the Kinvey File API if you wish to include a `Content-Type` header when uploading your file to Google Cloud Storage

Optional query parameters

Parameter	Applies to	Default	Short description
query	GET		Execute a complex query
ttl_in_seconds	GET	3600	If set, Google Cloud Storage URLs will expire after the specified amount of time
tls	POST, PUT, GET	false	If true, Google Cloud Storage URLs will use the `https` protocol instead of `http`

kinveyfile_ttl	KinveyFiles	3600	If set, Google Cloud Storage URLs will expire after the specified amount of time
kinveyfile_tls	KinveyFiles	false	If true, Google Cloud Storage URLs will use the `https` protocol instead of `http`

Guides

Files