Dataset

The dataset APIs allow you to manipulate (create, read, update and delete) your project data.

The API endpoint is:

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

Where <dataset-name> is the (case-sensitive) name of the dataset to manipulate.

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

When inserting or updating a record the following rules apply:

  • Immutable fields are optional (e.g. idcreated_atupdated_at). 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.

Create records

POST https://<project-id>.app.jexia.com/ds/<dataset-name>

The request body can be a JSON object to insert a single record:

{
  "text_field": "some text",
  "number_field": 42,
  "etc": "etc"
}

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

[
    {
        "text_field": "some text",
        "number_field": 42,
        "etc": "etc"
    },
    {
        "text_field": "some other text",
        "number_field": 24,
        "etc": "etc"
    }
]
  • 200
    Record(s) created successfully. Response contains the full record(s) including its default 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 insert the record(s) into this dataset.
  • 404
    Dataset not found
  • 500
    There is an internal error

Fetch records

GET https://<project-id>.app.jexia.com/ds/<dataset-name>?<filter-parameters>
  • 200
    All (filtered) records from the given Dataset including child records (assuming the access token has permissions to read those)
  • 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 dataset or related child datasets.
  • 404
    Dataset not found
  • 500
    There is an internal error

Delete a record

DELETE https://<project-id>.app.jexia.com/ds/<dataset-name>?<filter-parameters>

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/ds/<dataset-name>?cond=[{"field":"id"},"=","005c8679-3fad-46fd-a93f-9484ea8ff738"]

There is nobody in this request.

  • 200
    Dataset record(s) have been successfully deleted.
  • 401
    Invalid authentication. Access token was not provided or incorrect.
  • 403
    Forbidden. Access token does not have permission to delete the record(s).
  • 404
    Dataset or Record ID not found
  • 500
    There is an internal error

Update records

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

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

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

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

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

{
  "id": "cefd5026-4279-405a-9931-e47b76425027",
  "text_field": "some text",
  "number_field": 42,
  "etc": "etc"
}

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

[
    {
        "id": "cefd5026-4279-405a-9931-e47b76425027",
        "text_field": "updated text",
        "number_field": 42,
    },
    {
        "id": "8f05b516-36a8-4923-b85a-0b9bfa6296e9",
        "number_field": 24,
        "etc": "enz"
    }
]

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 JSON entries of this array are applied cumulatively where the last record wins. So if there would not be any  id fields in the example, the number_field would contain 24.

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

  • 201
    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 dataset.
  • 404
    Not found. Dataset is not found.
  • 500
    There is an internal error
https://{{projectID}}.app.jexia.com/ds/owner
[
	{
		"name":"Ilon",
		"surname":"Mask",
		"cars": [{
			"type":"Tesla",
			"model":"PD100",
			"year":"2016/08/16",
			"price":4326,
			"available":true
		}]
	}
]

to get related data,  I need to execute next call:

GET https://<your-app-id>.app.jexia.com/ds/<your-dataset>?outputs=["<related_dataset>"]

for our example it will be:

https://{{projectID}}.app.jexia.com/ds/owner?outputs=["cars"]

I can also fetch only particular fields from related record:

https://{{projectID}}.app.jexia.com/ds/owner?outputs=["cars.price","cars.model"]

Filtering

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

  • response fields (outputs) - use to select which fields should be returned in the response
  • filtering (cond) - Apply filters/conditions to limit the records that are influenced
  • pagination (range) - to select a range of records to apply the request to
  • sorting (sort) - Sort the resulting records in the response

Below you can find a video which is explain how to use filtering with REST API:

Response fields

Optional <filter-parameter> to select which fields should be part of the response. If outputs is not provided, all fields of the dataset are returned.

outputs=[<field name>,...]

The outputs array is the list of fields that should be included in the result.

Nested fields can be used for JSON fields, relations and schemaless data:

  • relation
  • relation.child_field
  • json_field.nested_field
  • schemaless_field
  • schemaless_field.nested

Filter parameters

Optional <filter-parameter> to select which record(s) the request is applied to. If it is not provided the request is applied on all records.

cond=[<expression>, <comparator>,<expression>|<nested cond>, [<operator>, <expression>, <comparator>",<expression>|<nested cond>, [...]]]

The cond array must contain triples of values: <expression><comparator> and <expression>, or a <nested condition>. A <nested condition> has the same syntax as a cond., so it is an array of <expression><comparator><expression> or a <nested cond> as well.

Multiple queries within a (nested) condition are combined using <operator>.

  • <expression> can be a constant (string, number, boolean, etc.) or an object.
    The object has a single key/value pair, where the key can be “field” only (for now, later more types will be added), and the value for field type is the <field name>
  • <comparator> and <value> can have the following values:

Comparator group

<comparator> <value> Applicable field types

Equality comparators

“>”, “<”, “=”, “!=”, “>=”, “<=”

single value matching field type

all fields

Emptiness comparators

“null”

true or false

all fields

Range comparator

“between”

[start, end]

textual, numbers, date/times

Array comparators

“in”, “not in”

Array of allowed values (matching field type)

all fields

Pattern comparator

“like”

string value

textual

Regex comparator

“regex”

string value

textual

  • <operator> can be "and", "&&", "or" or "||"

Pagination: limit and offset

Optional <filter-parameter> to select a range of records to return in the response. If it is not provided the response will contain all (selected) records.

range={"limit": 5, "offset": 3}

The range may contain two values: <offset> and <limit>

  • <offset> is an integer defining the starting point of the results (the first record is 0)
  • <limit> is an integer defining how many records should be returned.
  • If the limit is provided with 0, all results will be returned.
  • Request can contain <offset><limit> or both.

Sorting

Optional <filter-parameter> to define the order of returned response records. If this is not provided random/undefined (i.e. default of data storage) sorting is returned.

order={"direction":"asc|desc","fields":["field_one","field_two","field_N"]}

The order must contain two entries: <fields> and <direction>

  • <direction> can contain asc (for ascending) or desc (for descending)
  • order can be provided multiple times in URL to mix ascending and descending orders in the same query. The order these parameters are provided is important. Query below will first do ascending order on first_field and then do descending order on second_field.[?order={"direction":"asc","fields":["first_field"]}&order={"direction":"desc","fields":["second_field"]}

Attach/Detach records

It is possible to attach or detach existing, related records from their parents using the Filter parameters described above.

On either a PUT or a PATCH request (there is no difference) you can add action parameter, with either attach or detach as a value. For example

PUT https://<your-app-id>.app.jexia.com/ds/<your-dataset>?action=attach&cond=...&action_cond=...&action_resource=...&action_etc=...

This example applies cond on the parent records and action_cond on the child records and attaches all 'parent list' entries to the 'child list' entries. With simple conditions using the ids of the records you can easily attach 2 records, with more complex conditions you can do more powerful operation.

For example, assume there is an accountants dataset with some field including role and another orders dataset (related to accountants) with some fields including total_value. Attaching all records containing orders with a value bigger than 100.000 to all senior accountants can be done in the following way:

PUT https://<your-app-id>.app.jexia.com/ds/accountants?action=attach&cond=[{"field":"role"},"=","senior"]&action_cond=[{"field":"total_value"},">",100000]&action_resource=orders

Besides the Filter parameters described above, the following action-related parameters are available:

Parameter Type/Value Description
action "attach"/"detach" Select the action to perform
action_cond JSON array Condition for the action (to select the child records)
same as Filter parameter filtering
action_resource string Name of the child resource must be accessible via relation from parent
action_order JSON object same as Filter parameter order
action_range JSON object same as Filter parameter range