API Guide improvements: add images related to Fibery UI

Ideas & Features
1

“A picture is worth a 1000 words”.

I’m now trying to hack my understanding of API to update data in my workspace via n8n.

What would ease is having some images to visually connect API-based data structures to their respective entities & fields in Fibery UI.

The logic of query structures reminds me SQL. But currently I have to make quite some effort to understand new structures given it’s not a typical API I’m used to + I face some errors. :slight_smile:

2

Can you upload a simple sketch of what you think a useful image would be. I’m struggling to visualise something that would clarify what is essentially a very code-heavy topic to talk about.

3

API Query error entity.error/schema-field-not-found - #2 by Chr1sG - typical example trying to understand how field names in API corelate to the field names in Fibery. It was an “unclear & surprising discovery” that I should use spaceName/fieldName notation to refer to fields in API. My initial thought was it should have been something like tableName/fieldName instead.

4

Is there an example of an image that might have accelerated this discovery for you?

5

Ok, will do later today

6

Basically, when I was studying the Entity API reference I got confused with “Cricket/Player“ sample. Don’t ask me why. :slight_smile: Something didn’t click there. Perhaps, for me personally I’d rather prefer something like “Company/Employee“ or “Folder/File“ or “CRM/Person“ instead.

Since this is not a straightforward REST API, it takes quite some time with trial & errors, especially at the beginning to making the connections between the entities & their properties on the API level and the actual workspace I have in place. Therefore, visualization could ease getting started.

So, I’d love see how this:

image
image865×313 33.1 KB

would map to this:

curl -X POST https://YOUR_ACCOUNT.fibery.io/api/commands \
     -H 'Authorization: Token YOUR_TOKEN' \
     -H 'Content-Type: application/json' \
     -d \
      '[
         {
           "command": "fibery.entity/query",
           "args": {
             "query": {
               "q/from": "Cricket/Player",
               "q/select": [
                  "fibery/id",
                  "fibery/public-id",
                  "Cricket/name",
                  "Cricket/Full Name",
                  "Cricket/Born",
                  "Cricket/Shirt Number",
                  "Cricket/Height",
                  "Cricket/Retired?",

                  { "Cricket/Batting Hand": ["enum/name"] },
                  { "Cricket/Current Team": ["Cricket/name"] },
                  { "user/Former Teams": { "q/select": ["Cricket/name"], "q/limit": "q/no-limit" } },
                  { "# of former teams": [ "q/count", ["user/Former Teams", "fibery/id"] ] }
                ],
               "q/where": [">=", ["Cricket/Born"], "$birthday" ],
               "q/order-by": [
                 [["Cricket/Height"], "q/desc"],
                 [["Cricket/Born"], "q/asc"]
               ],
               "q/limit": 3
             },
             "params": {
              "$birthday": "1986-01-01"
             }
           }
         }
       ]'

Now, I understand the notation a bit more.

What’s confusing though is things like:

                  "Cricket/name",
                  "Cricket/Full Name",

In my head name and Full Name belong to the table (Player) - not the database (Cricket). What if we have a table Referee with similar fields like name and Full Name?

7

I think the terminology is wrong here I’m afraid (at least, using Fibery terms)

In the API example, Cricket is the space name, and within the Player database there is a field, whose title is Name, but whose name (according to the API) is Cricket/name.
There indeed could be another database called Referee which also has a field whose title is Name, but whose name (according to the API) is Cricket/name.
However, since an entity query is always made to a single database (using "q/from": "<spacename>/<databasename>") there is no chance of these fields being mistaken for each other.

1 Like