Resources

Introduction#

The term resource represents data entity abstraction and a mechanism for CRUD operations against it on your project API. You can look on it as a single table in database. Once you get your project API up and running, you will have ability to dynamically define and create your custom API resources.

Number of resources you can have on a project isn't limited. Also, a name of a resource can be anything, but we highly recommend using plural nouns in order to follow REST naming conventions.

note

If you are using one of our official SDK libraries you will not be able to create a resource with names users and files because these names are reserved for project users and files resource.

The term record represents a single entry in your table, while a collection would be a list of records.

Structure of resource data is flexible, and it does not have to be uniform. Every record can have different structure.

Basic concepts#

The URL of your API resource is https://{app-id}.essentialz.cloud/api/{resource-name} where app-id is id of your project, and resource-name obviously a name of the resource.

Creating a resource#

To create a resource it's only necessary to create it's first record. If the resource didn't exist before, API will bootstrap the resource routes, and you will get all CRUD actions available instantly.

Records and Collections#

Resource API is organized according to the REST API standard.

Below you can read which endpoints exist and how these should be used for managing records and collections.
There are also real life usage examples.

Creating a record#

POST https://{app-id}.essentialz.cloud/api/{resource-name}

Record can be anything formatted as a JSON object that you want to store inside your database.

Creating a record dispatches an event {resource-name}_created.

Learn more about Events & Webhooks

Example

Here is the example of how it would look like to create a record on cars resource.

curl
fetch

Request

curl --location --request POST 'https://example.essentialz.cloud/api/cars' \
--header 'Content-Type: application/json' \
--data-raw '{
  "brand": "peugeot",
  "model": "3008",
  "production_year": "2019",
  "fuel": "diesel"
}'

Response

{
    "brand": "peugeot",
    "model": "3008",
    "production_year": "2019",
    "fuel": "diesel",
    "id": "318ae317-bdc8-4799-8d40-0b6817436506",
    "created_at": "2021-09-23 18:58:55 UTC",
    "updated_at": "2021-09-23 18:58:55 UTC"
}

Updating a record#

PUT https://{app-id}.essentialz.cloud/api/{resource-name}/{record-id}

Updating a record dispatches an event {resource-name}_updated.

Example

Here is the example of how we would update the previously created record.

curl
fetch

Request

curl --location --request PUT 'https://example.essentialz.cloud/api/cars/318ae317-bdc8-4799-8d40-0b6817436506' \
--header 'Content-Type: application/json' \
--data-raw '{
  "brand": "peugeot",
  "model": "3008",
  "production_year": "2021",
  "fuel": "petrol"
}'

Response

{
  "fuel": "petrol",
  "brand": "peugeot",
  "model": "3008",
  "production_year": "2021",
  "id": "318ae317-bdc8-4799-8d40-0b6817436506",
  "created_at": "2021-09-23 18:58:55 UTC",
  "updated_at": "2021-09-23 19:05:32 UTC"
}

Fetching a record#

GET https://{app-id}.essentialz.cloud/api/{resource-name}/{record-id}

Example

curl
fetch

Request

curl --location --request GET 'https://example.essentialz.cloud/api/cars/318ae317-bdc8-4799-8d40-0b6817436506' \
--header 'Content-Type: application/json'

Response

{
  "fuel": "petrol",
  "brand": "peugeot",
  "model": "3008",
  "production_year": "2021",
  "id": "318ae317-bdc8-4799-8d40-0b6817436506",
  "created_at": "2021-09-23 18:58:55 UTC",
  "updated_at": "2021-09-23 19:05:32 UTC"
}

Fetching a collection#

GET https://{app-id}.essentialz.cloud/api/{resource-name}

Example

curl
fetch

Request

curl --location --request GET 'https://example.essentialz.cloud/api/cars' \
--header 'Content-Type: application/json'

Response

[
  {
    "fuel": "petrol",
    "brand": "peugeot",
    "model": "3008",
    "production_year": "2021",
    "id": "318ae317-bdc8-4799-8d40-0b6817436506",
    "created_at": "2021-09-23 18:58:55 UTC",
    "updated_at": "2021-09-23 19:05:32 UTC"
  },
  {
    "fuel": "diesel",
    "brand": "bmw",
    "model": "320d",
    "production_year": "2002",
    "id": "0004018e-a164-45ac-b15b-4038733552f3",
    "created_at": "2021-09-23 19:47:16 UTC",
    "updated_at": "2021-09-23 19:47:16 UTC"
  },
  {
    "fuel": "petrol",
    "brand": "citroen",
    "model": "c3",
    "production_year": "2018",
    "id": "00af780f-cf31-4243-a945-e80eb52a6467",
    "created_at": "2021-09-23 19:47:50 UTC",
    "updated_at": "2021-09-23 19:47:50 UTC"
  }
  ...
]

Pagination#

Pagination is enabled by default on all of your Architect entities, with a default page size of 20. To change the page size when listing entities, send a PER_PAGE header along with your request.

note

Maximum page size is 100. Enterprise users can change this.

In the response headers of your request, you will get a TOTAL_PAGES value according to provided PER_PAGE parameter. To navigate trough pages, just add PAGE parameter to request headers.

Filtering#

This endpoint also provides a mechanism for querying & filtering records.
Filtering records comes down to building a query string and sending a request with it.

GET https://{app-id}.essentialz.cloud/api/{resource-name}?{query-string}

Below are presented some complex queries as JSON, just to make these more readable. You can also build your queries as JSON objects. For converting JSON to query strings we recommend using query-string library or similar.

Exact match#

If you want to select only records with exact property values, you can do it in the following way.

JSON
Query string

{
  "brand": "citroen",
  "model": "c5"
}

Contains filter#

Keyword _contains is used whenever we want to get records with properties that partially match provided value.

If we wanted to get all todos that contain the word milk in their title, our parameters would look like this:

JSON
Query string

{
  "brand": {
    "_contains": "citro"
  }
}

Min / max filter#

Keywords _min & _max should be used whenever we want to select records that belongs to specific range of property values.

JSON
Query string

{
  "brand": {
    "_contains": "peug",
  },
  "created_at": {
    "_min": "2021-07-11 15:25:07 UTC",
    "_max": "2021-10-19 15:25:07 UTC"
  }
}

Nested fields#

If ypu want to search deeper in your record's data you can nest properties according to the structure of your resource objects.

JSON
Query string

{
  "details": {
    "serial_number": {
      "_contains": "xxx"
    }
  }
}

Array contains filter#

Say we want to filter only the todos that have "groceries" and "apples" categories. We would accomplish that using the _arr_contains filter.

JSON
Query string

{
  "categories": {
    "_arr_contains": "groceries"
  }
}

And / or operations#

In a more complex scenario, we can also use the _or and _and keywords.

In this example, we'll try to fetch todos that are either named Buy milk, or are named Try Architect and assigned to anyone named John. The query, represented in JSON format, would look like this:

JSON
Query string

{
  "_or": [
    {
      "brand": "mercedes",
    },
    {
      "_and": [
        {
          "brand": "bmw"
        },
        {
          "details": {
            "serial_number": {
              "_contains": "xxx"
            }
          }
        }
      ]
    }
  ]
}

Deleting a record#

DELETE https://{app-id}.essentialz.cloud/api/{resource-name}/{record-id}

Deleting a record dispatches an event {resource-name}_deleted.

Example

Eventually, at some point we would probably like to delete previously created record.

curl
fetch

Request

curl --location --request DELETE 'https://example.essentialz.cloud/api/cars/318ae317-bdc8-4799-8d40-0b6817436506'

Response

{}

See more#

Protecting your resources using Scopes & Policies
Managing Events & Webhooks