All files uploaded through any application module will be stored in the Media Vault module. When we want to expose some of those files to end users, that’s where Files module comes in - opening Media Vault to general public would lead to all sorts of security issues. This module gives you the option to define fine-grained access control over individual objects (files), for specific users and/or user roles.

Files Stream

Similarly to the Media Vault module, there’s a difference between Files and File stream functionality and endpoints. File Stream represents an actual resource in your application (document, image, video…), and Files holds the information about these resources (the type of extension, file size, description…).

Endpoints

  • GET - used to retrieve a Files stream resource (document, image, video, etc.).
  • POST - used to upload a resource into the Files module.
  • PUT - used to update already existing resource in the Files module.

Files

Files endpoints let you manage the information about the resources stored in the Files module.

Endpoints

  • GET - used to retrieve a media vault resource.
  • GET by search criteria - used to retrieve a (filtered|sorted|paged) collection of Files resources that match the specified criteria from the Baasic system. To see parameters used for this request, click here.
  • PUT - used to update a Files resource.
  • PUT batch - used to update collection of Files resources.
  • UNLINK - used to unlink a Files resource.
  • UNLINK batch - used to unlink a collection of Files resources.

Let’s see these endpoints in action.


Create new File stream (POST)

Here’s how you can create a new file stream in the Files module via POST method (similar to Media Vault stream PUT):

curl
-X POST
-H "Authorization: bearer <access-token>"
-H "Content-Type: multipart/form-data"
-F "File=@[object Object]"
"http://api.baasic.com/<version>/<api-key>/file-streams/images/<file-name>"

If the file is successfully uploaded, you should get a response code 201 (Created) along with this:

{
    "description": "",
    "derivedEntries": [],
    "fileExtension": ".jpg",
    "fileName": "image1",
    "fileSize": 494696,
    "height": 1365,
    "metaData": {
        "XResolution": "1"
    },
    "ownerUser": null,
    "ownerUserId": "bQtZG36zG23DQDC8098990",
    "path": "/images/image1.jpg",
    "policies": [],
    "width": 2048,
    "dateCreated": "2016-06-01T08:24:53.669801",
    "dateUpdated": "2016-06-01T08:24:53.669801",
    "id": "Fd3FWBJzhwTUPLCC05yiz1"
}

Retrieve a file stream (GET)

If you perform a GET request on a File Stream endpoint using a file ID like this

curl
-X GET
-H "Authorization: bearer <access-token>"
"http://api.baasic.com/<version>/<api-key>/file-streams/<file-id>"

you will get 200 OK HTTP response code, along with the requested file stream - and if you want to retrieve the information about the file, use Files GET method.

Update File stream (File stream PUT)

Since working with File Stream means you’re working directly with the underlying file, updating the file means replacing it with another file. Note that the formats of both files, replaced and the new one, don’t have to be the same.

curl
-X PUT
-H "Authorization: bearer <access-token>"
-H "Content-Type: multipart/form-data"
-F "File=@[object Object]"
"http://api.baasic.com/<version>/<api-key>/file-streams/images/<file-name>"

This should replace image1.jpg with another file, and as a response, give the code 204 (the server successfully processed the request, but is not returning any content).

Retrieve information about a file (Files GET)

To retrieve information about a certain file, add the file ID to the GET request on the Media Vault endpoint:

curl
-X GET
-H "Accept: application/json"
-H "Authorization: bearer <access-token>"
"http://api.baasic.com/<version>/<api-key>/files/<file-id>"

Result (HTTP code 200; OK):

{
    "description": "",
    "derivedEntries": [],
    "fileExtension": ".jpg",
    "fileName": "image1",
    "fileSize": 15536,
    "height": 640,
    "metaData": {},
    "ownerUser": null,
    "ownerUserId": "bQtZG36zG23DQDC8098990",
    "path": "/images/image1.jpg",
    "policies": [],
    "width": 709,
    "dateCreated": "2016-06-01T08:24:53.669801",
    "dateUpdated": "2016-06-01T08:24:53.669801",
    "id": "Fd3FWBJzhwTUPLCC05yiz1"
}

The GET method can be used with file name, as well as with file ID.

Files Search (GET by search criteria)

Mobile and web applications can have thousands of files, that’s where GET by search comes in handy. It’s used to retrieve a (filtered|sorted|paged) collection of file resources that match the specified criteria. To see parameters used in this request, click here.

Update information about a file (Files PUT)

This updates the file information - not the file itself. If you want to update the file (replace it), use the Files Stream PUT.

curl
-X PUT
-H "Authorization: bearer <access-token>"
-H "Content-Type: application/json"
-d '{
    "path":"/simple_text.txt", 
    "description":"Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque vel vulputate mauris. Ut ultrices lectus justo, quis aliquet lorem commodo sit amet.",
    "ownerUserName": "bQtZG36zG23DQDC8098990" 
}'
"http://api.baasic.com/<version>/<api-key>/files/<file-id>"

Response: 204 (the server successfully processed the request, but is not returning any content).

curl
-X DELETE
-H "Content-Type: application/json"
-H "Authorization: bearer <access-token>"
"http://api.baasic.com/<version>/<api-key>/files/<file-id>"

Response: 204 (the server successfully processed the request, but is not returning any content).

To update a collection of file resources, use PUT batch; and to unlink a collection, use the UNLINK batch request.

Linking resources

curl
-X POST
-H "Authorization: bearer <access-token>"
-H "Content-Type: application/json"
-d '[{
    "path":"/simple_text.txt",
    "ownerUserName": "bQtZG36zG23DQDC8098990" 
}]'
"http://api.baasic.com/<version>/<api-key>/files/batch/link"

If linking is successful, you should get a response code 201 (Created) along with this:

[
    {
        "description": null,
        "derivedEntries": [],
        "fileExtension": null,
        "fileName": null,
        "fileSize": 0,
        "height": null,
        "metaData": null,
        "ownerUser": null,
        "ownerUserId": null,
        "path": null,
        "policies": [],
        "width": null,
        "dateCreated": "2016-06-01T11:33:28.826051",
        "dateUpdated": "2016-06-01T11:33:28.826051",
        "id": "f5xshRGiqqYw7gOO0GzvF0",
        "ownerUserName": "bQtZG36zG23DQDC8098990"
    }
]

Permissions

Files module allows you to use object-level ACLs (Access Control List) to set up access control over individual objects/files. These single-object-permissions can also be set for specific users and/or user roles.

Read more on Baasic modules permissions here.

Feel free to leave a comment

comments powered by Disqus