Fileset

The Fileset APIs allow you to manipulate (create, read, update and delete) your project files. This API is very similar to the Dataset API by design, so make sure to also refer the following video.

So lets deep dive into the API's of fileset.

Following is the fileset API endpoint using which you will do all your fileset operations:

https://<project-id>.app.jexia.com/fs/<fileset-name>?<filter-parameters>

Here <fileset-name> is the (case-sensitive) name of the fileset you will be operating on.

All endpoints (except for create) have filter parameters (<filter-parameters>) to filter the records on which the request applies and to fine-tune the results.

When uploading or updating a file (record) the following things should be kept in mind:

  •  Each fileset contains a set of immutable fields. Some of them are id, created_at, updated_at, size, type, url and status. These fields are generally used to contain the metadata of the file which is filled internally by our API's. It is not possible to change the structure of these fields neither their values. These fields are optional in the fileset request. If a request contains an immutable field, its value must be its current value. Otherwise, it'll fail with a bad request (400).

  • If a request contains an unknown field, it gets added automatically as a schemaless field for this record.

The fileset records contain the metadata of the file, besides the custom fields there are some predefined ones:

  • name - Name of the file
  • size - Size of the file
  • type - File type (supported types, note not mime-types and if the type is not found the extension is stored)
  • url - Public URL to the file
  • status
    • in_progress - Jexia is still processing the file
    • succeeded - File got uploaded and processed successfully
    • failed - something went wrong during upload or processing of the file

Fileset  API consists of 4 endpoints right now. Let us deep dive into them one by one

Upload a file

Post - This endpoint is used to upload a file and store some data associated with it. The endpoint used to upload a file is following.

POST https://<project-id>.app.jexia.com/fs/<fileset-name>

⚠️ This endpoint uses multipart/form-data as the content type for the request ⚠️

"Content-Type": "multipart/form-data;boundary=boundary"

The boundary value is just an example and you can use any (valid) boundary.

Each request consists of two parts:

1) data - It has to be sent with your data key in your multipart/form request. I can be used to store metadata of your file or any other data that you want to associate with your file. As mentioned above if data contains an unknown field, it gets added automatically as a schemaless field for this record. The values of the data have to be a JSON object containing all the data related to file.

2) file - file can be sent under any key as you like. It contains your actual file.

The body has to be sent as form data.  Following is an example of a request:

--boundary 
Content-Disposition: form-data; name="description" 
 
this is my file 
--boundary 
Content-Disposition: form-data; name="file"; filename="my_file.txt" 
 
<file data>
--boundary--

Note: Only one file can be uploaded per request for now. If there are multiple files in the body, only the first one will be processed and rest all will be ignored.

When you submit a file request you will receive back the request ID along with status. Most of the other metadata will be either empty or null.

This is because when you submit a request to us we process the file and based on the size of file it might take us some time to process it. So we immediately return a response. The status at this time will be in progress.

When the process is finished and the file is uploaded we will send you an event via RTC to notify you of the status change. The final status can be a success or error depending on if the file was uploaded successfully.

You can read on how to subscribe to resources and get events related to them on our RTC documentation.

Following are the status codes you might get as a response:

  • 201
    File got uploaded successfully, and it is being processed by Jexia. Most returned fields are still empty, as Jexia is processing the file in the background after it gets uploaded and the response is returned. Use Realtime Communication API to get events on updates of this record and fetch the updated fields.
  • 400
    Bad request. Request was somehow malformed and was not executed.
  • 401
    Invalid authentication. Access token was not provided or incorrect.
  • 403
    Forbidden. Access token does not have permission to upload the file into this fileset.
  • 404
    Fileset not found.
  • 500
    There is an internal error.

Fetch file (metadata)

Get - You can use this endpoint to fetch a list of files from a fileset. You will use the following url to access it.

GET https://<project-id>.app.jexia.com/fs/<fileset-name>?<filter-parameters>

You will receive a list of files records with their data. Following is a sample of data you will receive:

[
    {
        "id": "4fcbda1c-0ac8-496b-8330-404d146cc544",
        "created_at": "2019-09-05T14:57:15.137245Z",
        "updated_at": "2019-09-05T14:57:15.79467Z",
        "name": "allow-camera.js",
        "size": 820,
        "type": "js",
        "url": "https://s3.eu-central-1.amazonaws.com/bucket-name/allow-camera_11d981f1-39e5-4199-8a67-d591e6e766ea.js",
        "status": "completed",
        "test": "someuser"
    }
]

Here URL is url of the uploaded file. 

Following is the list of status codes,  you can expect as a response.

  • 200
    All (filtered) records from the given Fileset including child records (assuming the access token has permissions to read those). The filled url field can be used as a (public) download link to the file.
  • 400
    Bad request. Request was somehow malformed and was not executed.
  • 401
    Invalid authentication.
  • 403
    Forbidden. Access token does not have permission to read the record(s) of this fileset or related child filesets.
  • 404
    Fileset not found.
  • 500
    There is an internal error.

Update file (metadata)

Use PUT to update the full record/metadata, all missing fields are reset to their default values:

PUT https://<your-app-id>.app.jexia.com/fs/<your-fileset>?<filter-parameters>

Or use PATCH for a partial update, only provided fields will be updated.

PATCH https://<your-app-id>.app.jexia.com/fs/<your-fileset>?<filter-parameters>

The request body can be a JSON object to update a single record.

{
    "id": "8be0bfc7-949e-4013-94d1-1c3c60236fe2",
    "description": "updated description",
}

Or it can be an array of JSON object to update multiple records:

[
    {
        "id": "8be0bfc7-949e-4013-94d1-1c3c60236fe2",
        "description": "updated description",
    },
    {
        "id": "8f05b516-36a8-4923-b85a-0b9bfa6296e9",
        "description": "final description",
    }
]

JSON array is recommended when multiple records need to be updated in a single go, as it is an 'all or nothing' implementation, so you can keep the data consistent. When you use a JSON array, the records are applied cumulatively where the last record wins. So if there would not be any  id fields in the example, the description field will contain "final description".

For safety reasons, either the id field in the request or some condition in the <field-parameters> must be provided.

In responds you can get next :

  • 200
    Record(s) have been updated successfully. Response contains the modified record(s).
  • 400
    Bad request. Request was somehow malformed and was not executed.
  • 401
    Invalid authentication. Access token was not provided or incorrect.
  • 403
    Forbidden. Access token does not have permission to update the record(s) of this fileset.
  • 404
    Not found. Fileset is not found.
  • 500
    There is an internal error.

Delete file (metadata)

It is required to use the <filter-parameters>(to prevent you from accidentally destroying all data/records in the dataset!)

For example to delete a single record filtered by its id use:

DELETE https://<project-id>.app.jexia.com/fs/<fileset-name>?cond=[{"field":"id"},"=","8be0bfc7-949e-4013-94d1-1c3c60236fe2"]

in responds you will get next codes:

  • 200
    Fileset record has been successfully deleted.
  • 400
    Bad request. It's returned when: request data could not be parsed. Request tries to update update an immutable field. If request contains an unknown field. If request is missing a required field.
  • 401
    Invalid authentication. Token is either missing in the request or it's an invalid token.
  • 403
    Forbidden. Token is valid but it's not authorized to perform DELETE operation on the fileset.
  • 404
    Not found. Either fileset or record is not found.
  • 500
    There is an internal error.

⚠️ Only the metadata is deleted the actual file (in the corresponding storage) is not deleted. ⚠️