Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
protogrid:json_api_database_views [2020-12-22 15:58] – dru | protogrid:json_api_database_views [2023-01-10 23:16] (current) – [Standard Views Decommissioned With Version 2.6.0] dru | ||
---|---|---|---|
Line 3: | Line 3: | ||
A Database View can be seen as a table with two columns. The first column is called ' | A Database View can be seen as a table with two columns. The first column is called ' | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
Line 14: | Line 13: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 22: | Line 20: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 30: | Line 27: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
} | } | ||
Line 39: | Line 35: | ||
For details about listings / views and how to request it, please see section about view [[protogrid: | For details about listings / views and how to request it, please see section about view [[protogrid: | ||
+ | |||
+ | For newcomers: In 90% of use cases, the [[# | ||
===== Protogrid Standard Views ===== | ===== Protogrid Standard Views ===== | ||
- | ==== all_by_id | + | |
+ | ==== Simple Overall Views ==== | ||
+ | |||
+ | === all_by_id | ||
This view basically lists all the ids of all the Cards. The row values are null (i.e. unused). The result is paged, which means that you might need several requests to load all the ids. To load the next page, you can use the " | This view basically lists all the ids of all the Cards. The row values are null (i.e. unused). The result is paged, which means that you might need several requests to load all the ids. To load the next page, you can use the " | ||
Line 50: | Line 51: | ||
Example respond: | Example respond: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
- | | + | |
], | ], | ||
" | " | ||
- | | + | |
- | " | + | " |
- | " | + | " |
- | ], | + | ], |
- | " | + | " |
- | | + | |
}, | }, | ||
... | ... | ||
- | | + | |
- | } | + | |
} | } | ||
+ | } | ||
</ | </ | ||
- | ==== by_id ==== | + | === by_id === |
This View contains all non-deleted and non-hidden Card IDs as keys. The value is null. This gives you fast access to all the Card IDs in your Application. This can be useful for example when doing some kind of synchronization and checking for new documents. | This View contains all non-deleted and non-hidden Card IDs as keys. The value is null. This gives you fast access to all the Card IDs in your Application. This can be useful for example when doing some kind of synchronization and checking for new documents. | ||
Line 79: | Line 78: | ||
https:// | https:// | ||
</ | </ | ||
+ | |||
+ | Please note that the " | ||
Example respond (be aware, that this Card is a System Card and therefore looks different to the typical Cards): | Example respond (be aware, that this Card is a System Card and therefore looks different to the typical Cards): | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
Line 187: | Line 187: | ||
"&& | "&& | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 196: | Line 195: | ||
</ | </ | ||
- | ==== deleted_by_sortstring_and_id | + | ==== Overall Views With Filtering/ |
- | This view contains the IDs of all the deleted Cards as keys. The value is null. The request and response are analog to view [[# | + | |
- | ==== by_proto_and_sortstring_and_id | + | === by_sortstring_and_id |
- | This view contains all non-deleted and non-hidden Cards with corresponding Proto by id. The key is composed of the Proto key, the Card sorting string and the Card key. The value is null. This view can be used to get all Cards belonging to a special Proto given the Proto key. | + | |
- | Example Request to get all Cards belonging to the Proto with key " | + | === by_design_element_and_sortstring_and_id === |
+ | |||
+ | === by_design_element_and_value_and_sortstring_and_id === | ||
+ | This view contains | ||
< | < | ||
- | https:// | + | ["234486c7-939f-49f4-88b2-6fd51369a1d9", "Basic Toilet 2016 ", "Basic Toilet 2016 ", "d81047c2-0d92-48ee-a352-f0c8d4e63b2b"] |
- | </ | + | |
- | + | ||
- | We use "null" and " | + | |
- | + | ||
- | Example respond: | + | |
- | <code json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | "CWH ONE", | + | |
- | " | + | |
- | ], | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | ... | + | |
- | ] | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | + | ||
- | + | ||
- | ==== by_search_term_and_sortstring_and_id ==== | + | |
- | This view contains Cards for a certain search term by id. The key is composed of the search term, the Card sorting string and the Card key. Search term means a specific string, for which you want to find all Cards containing this string in the values. You may not find Cards having this string only in the labels of the fields. Example: | + | |
- | <code json> | + | |
- | [" | + | |
</ | </ | ||
The value is null. | The value is null. | ||
- | **Be aware**: The search only goes over values stored in this Card. This may differ from the visual representation Card. For example when Card A references another Card, you see the Shortname of the referenced Card (say " | + | Example request to get all Cards, where the name (in my example having with fieldkey |
- | + | ||
- | Example request to find all cards containing the word "behavior": | + | |
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
- | " | ||
- | " | ||
- | " | ||
- | " | ||
- | ], | ||
" | " | ||
{ | { | ||
" | " | ||
- | "behavior", | + | "816950eb-1b70-41e2-89f5-5400f9636345", |
- | "ScriptLibrary: | + | "night knight PRO", |
- | "1475e62a-47d7-4a29-98c2-c89f50edd497" | + | "night knight PRO", |
+ | "9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9" | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
{ | { | ||
" | " | ||
- | "behavior", | + | "816950eb-1b70-41e2-89f5-5400f9636345", |
- | "ScriptLibrary: | + | " |
- | "1475e62a-47d7-4a29-98c2-c89f50edd497" | + | "nightTable 2.0 - furniture", |
+ | "f6e2f9c9-e061-46f4-ab8f-a2594c2b38ae" | ||
], | ], | ||
- | " | ||
" | " | ||
- | }, | + | } |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | ], | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | ... | + | |
] | ] | ||
} | } | ||
Line 291: | Line 242: | ||
</ | </ | ||
- | You might have duplicates in the code due to several occurrences of the same search term on the same Card. | + | ==== Proto Specific Views ==== |
- | ==== deleted_by_search_term_and_sortstring_and_id | + | === by_proto_and_sortstring_and_id |
- | This view contains all deleted Cards for a certain search term by id. The value is null. The request and response are analog to view [[# | + | This view contains all non-deleted |
- | ==== by_proto_and_search_term_and_sortstring_and_id ==== | + | Example Request to get all Cards belonging to the Proto with key " |
- | This view contains | + | |
< | < | ||
- | ["9c2bdd7d-05bd-4d16-8339-11116e737b3a", | + | https:// |
</ | </ | ||
- | Example Request to get all Cards of Proto "9c2bdd7d-05bd-4d16-8339-11116e737b3a" | + | We use " |
- | < | + | |
- | https:// | + | |
- | </ | + | |
- | Example | + | Example |
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
{ | { | ||
" | " | ||
- | "9c2bdd7d-05bd-4d16-8339-11116e737b3a", | + | "12532072-0d76-4457-8cf8-7847d0470738", |
- | "wants", | + | "CWH ONE", |
- | "Priscilla Molesworth | + | "4bcbdb7f-89c3-4640-b04e-3bd468df7c57" |
- | " | + | |
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 330: | Line 274: | ||
</ | </ | ||
- | ==== by_design_element_and_value_and_sortstring_and_id | + | === by_proto_and_design_element_and_sortstring_and_id |
- | This view contains all non-deleted and non-hidden Cards by design_element, | + | |
- | < | + | |
- | [" | + | |
- | </ | + | |
- | The value is null. | + | |
- | + | ||
- | Example request to get all Cards, where the name (in my example having with fieldkey " | + | |
- | < | + | |
- | https:// | + | |
- | </ | + | |
- | + | ||
- | Example response: | + | |
- | <code json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | "night knight PRO", | + | |
- | "night knight PRO", | + | |
- | " | + | |
- | ], | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | ], | + | |
- | " | + | |
- | " | + | |
- | } | + | |
- | ] | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | ==== by_proto_and_design_element_and_value_and_sortstring_and_id | + | === by_proto_and_design_element_and_value_and_sortstring_and_id === |
This view contains all non-deleted and non-hidden Cards by Proto, design_element, | This view contains all non-deleted and non-hidden Cards by Proto, design_element, | ||
< | < | ||
Line 383: | Line 285: | ||
Example Request to find all Cards based on Proto " | Example Request to find all Cards based on Proto " | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
Line 401: | Line 302: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 412: | Line 312: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
} | } | ||
Line 420: | Line 319: | ||
</ | </ | ||
- | ==== deleted_by_design_element_and_value_and_sortstring_and_id | + | ==== Views for Deleted Cards ==== |
- | This view contains all deleted Cards for a certain search term by design_element, | + | |
- | ==== all_protos_by_id ==== | + | === deleted_by_sortstring_and_id |
- | This view contains all Protos by id. The value contains shortname | + | This view contains |
- | Example request to get the first 5 protos: | + | === deleted_by_design_element_and_sortstring_and_id === |
- | < | + | This view contains all deleted Cards sorted by a certain design element. The value is null. The request and response are analog to view [[# |
- | https:// | + | |
- | </ | + | |
- | Example respond: | + | === deleted_by_design_element_and_value_and_sortstring_and_id === |
- | <code json> | + | This view contains all deleted Cards by a certain Proto, design_element, value, sortstring and id. The value is null. The request and response are analog to view [[# |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | "value": { | + | |
- | " | + | |
- | | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | | + | |
- | " | + | |
- | " | + | |
- | } | + | |
- | } | + | |
- | }, | + | |
- | | + | |
- | ] | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | ==== data_protos_by_sortstring_and_id | + | ==== Views for Navigation in Relational Tree (Up / Down) ==== |
- | This view lists all [[protogrid: | + | |
- | Example request to get all data Protos: | + | === related_keys_by_id === |
- | < | + | |
- | https:// | + | |
- | </ | + | |
- | + | ||
- | Example response: | + | |
- | <code json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | } | + | |
- | }, | + | |
- | ... | + | |
- | }, | + | |
- | " | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | ... | + | |
- | ], | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | ... | + | |
- | ], | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | ], | + | |
- | " | + | |
- | " | + | |
- | }, | + | |
- | ... | + | |
- | ] | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | + | ||
- | + | ||
- | ==== related_keys_by_id | + | |
This view contains all Cards by id. The value contains the related keys. | This view contains all Cards by id. The value contains the related keys. | ||
- | |||
- | **Be aware**: This is one of the very few views, where the key is **NOT** surrounded by "[ ... ]"! | ||
Example request to find all Cards related to the Card " | Example request to find all Cards related to the Card " | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
{ | { | ||
- | " | + | " |
- | | + | |
+ | | ||
" | " | ||
[ | [ | ||
Line 616: | Line 394: | ||
</ | </ | ||
- | ==== relating_cards_by_related_key ==== | + | === relating_cards_by_related_key_and_id |
This view contains all Relating Cards of the (Related) Card specified by key. The key is composed of the Related Card key and the Relating Card key. The value is null. | This view contains all Relating Cards of the (Related) Card specified by key. The key is composed of the Related Card key and the Relating Card key. The value is null. | ||
Example request to find all Cards relating to the (Related) Card with key " | Example request to find all Cards relating to the (Related) Card with key " | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
Line 636: | Line 413: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 644: | Line 420: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 652: | Line 427: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 660: | Line 434: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
}, | }, | ||
Line 668: | Line 441: | ||
" | " | ||
], | ], | ||
- | " | ||
" | " | ||
} | } | ||
Line 675: | Line 447: | ||
} | } | ||
</ | </ | ||
- | ==== tableview_data_by_id | + | |
+ | ==== Views for Direct Human Readable Presentation | ||
+ | |||
+ | === tableview_data_by_id | ||
This view contains all Cards contained in a tableview by id. The value contains the raw card. | This view contains all Cards contained in a tableview by id. The value contains the raw card. | ||
Line 684: | Line 459: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
{ | { | ||
- | " | + | " |
- | | + | |
+ | | ||
" | " | ||
"#": | "#": | ||
Line 733: | Line 508: | ||
</ | </ | ||
- | + | === shortname_objects_by_id | |
- | ==== shortname_by_language_objects_by_id ==== | + | This view contains all Cards which contain |
- | This view contains all Cards which contains | + | |
Example request to get the shortnames of the Card with key " | Example request to get the shortnames of the Card with key " | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | ||
" | " | ||
" | " | ||
{ | { | ||
- | " | + | " |
- | | + | |
+ | | ||
" | " | ||
" | " | ||
Line 762: | Line 536: | ||
</ | </ | ||
- | ==== sums_by_proto_and_design_element | + | ===== Views of Dedicated Search Dialog Boxes ===== |
- | Sums over the values | + | It is also possible to access |
- | - For number fields it produces the sum of values over the field. | + | |
- | - For text fields it produces the word count over all text entries. | + | |
- | - For relation fields it produces | + | |
- | - For date/time fields it produces | + | |
- | Example Request | + | Hint: For straight forward API usage in most cases it is recommended |
- | < | + | |
- | https:// | + | |
- | </ | + | |
- | Example Response: | + | Please note that Datetime Fields in Dedicated Search Boxes are indexed slightly differently than in normal views: If the date-time value is configured as a fixed filter field, the time component will always be set to 0 (example: "2021-11-11T00:00:00.000Z"). If the date-time value is configured as a sort field or filter field with range (greater/ |
- | <code json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | { | + | |
- | | + | |
- | " | + | |
- | | + | |
- | ], | + | |
- | " | + | |
- | } | + | |
- | ], | + | |
- | | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | ==== sums_by_proto_and_design_element_and_condition ==== | + | Example Request: |
- | Sums over the values of a field for all Cards of a [[Proto]] given a condition from another field. | + | |
- | + | ||
- | This endpoint requires four query key components: | + | |
- | - The Proto key | + | |
- | - The design element key for the field to sum over | + | |
- | - The design element key for the condition field | + | |
- | - The conditional value in the field specified in third key component | + | |
- | Example: What is the sum over all values in the “Total” field in the Proto “Invoice”, | + | |
- | + | ||
- | Depending on the field type to sum over (see key component 2 above) the endpoint returns: | + | |
- | - For number fields it produces the sum of values over the field. | + | |
- | - For text fields it produces the word count over all text entries. | + | |
- | - For relation fields it produces the number of stored relations. | + | |
- | - For date/time fields it produces the number of stored date/time values. | + | |
- | + | ||
- | Example Request | + | |
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
- | Example Response: | + | The key depends on the individually configured Filter Fields for the acessed Search Dialog Box. |
- | <code json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | { | + | |
- | "key": [ | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | ], | + | |
- | " | + | |
- | } | + | |
- | ], | + | |
- | " | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | ===== Views of dedicated Search Dialog Boxes ===== | + | ===== Change Log ===== |
- | It is also possible to access the views of dedicated [[protogrid: | + | ==== Standard Views Decommissioned With Version 2.1.5 ==== |
+ | * by_id_and_value | ||
+ | * by_proto_and_search_term_and_id | ||
+ | * by_search_term_and_id | ||
+ | * data_protos_by_id | ||
+ | * data_protos_by_search_term_and_id | ||
+ | * datetime_field_definitions_by_id | ||
+ | * datetime_field_definitions_by_search_term_and_id | ||
+ | * deleted_by_design_element_and_value_and_id | ||
+ | * deleted_by_id | ||
+ | * deleted_by_search_term_and_id | ||
+ | * logs_by_time_and_id | ||
+ | * navroot_candidates_by_design_element_and_value_and_id | ||
+ | * navroot_candidates_by_id | ||
+ | * navroot_candidates_by_search_term_and_id | ||
+ | * number_field_definitions_by_id | ||
+ | * number_field_definitions_by_search_term_and_id | ||
+ | * relational_definitions_by_id_and_related_proto | ||
+ | * text_field_definitions_by_id | ||
+ | * text_field_definitions_by_search_term_and_id | ||
- | Example Request: | + | ==== Standard Views Decommissioned With Version 2.2.1 ==== |
- | < | + | * by_design_element_and_value_and_id |
- | https:// | + | * by_proto_and_id |
- | </ | + | * by_proto_and_design_element_and_value_and_id |
+ | * deleted_by_proto_and_design_element_and_value_and_id | ||
+ | * navroot_candidates_by_design_element_and_sortstring_and_id | ||
+ | * navroot_candidates_by_design_element_and_value_and_sortstring_and_id | ||
+ | * sums_by_proto_and_design_element | ||
+ | * sums_by_proto_and_design_element_and_condition | ||
+ | * datetime_field_definitions_by_sortstring_and_id | ||
+ | * datetime_field_definitions_by_search_term_and_sortstring_and_id | ||
+ | * text_field_definitions_by_sortstring_and_id | ||
+ | * text_field_definitions_by_search_term_and_sortstring_and_id | ||
+ | * number_field_definitions_by_sortstring_and_id | ||
+ | * number_field_definitions_by_search_term_and_sortstring_and_id | ||
+ | * all_protos_by_id | ||
+ | * all_agents_by_id | ||
+ | * all_connectors_by_url_name | ||
- | The key depends on the individually configured Filter | + | ==== Adjustments to Views With Version 2.2.2 ==== |
+ | - All views: If a view is requested with the " | ||
+ | - All views: All string values as well as sortstrings are now cut off after 300 characters. | ||
+ | - All views: | ||
+ | - All views: The second last column " | ||
+ | - Dedicated Search Boxes: Now all filters must be set. An empty filter field in a Search Dialog Boxes now means a filter for those Cards where the target field is also empty. | ||
+ | - Dedicated Search Boxes: Datetime | ||
+ | - Dedicated Search Boxes with " | ||
+ | * For Relation/ | ||
+ | * For other field values: "< | ||
+ | * Note: It is anyway recommended to use Search Dialog | ||
+ | - In views " | ||
+ | * For Relation/ | ||
+ | * For other field values: "< | ||
+ | * Note: If you don't explicitly need sorting by design element value is anyway recommended to use the views " | ||
+ | - In views " | ||
+ | * View columns of " | ||
+ | * View columns of by_design_element_and_sortstring_and_id"" | ||
+ | |||
+ | ==== Standard Views Decommissioned With Version 2.6.0 ==== | ||
+ | * by_search_term_and_sortstring_and_id | ||
+ | * by_proto_and_search_term_and_sortstring_and_id | ||
+ | * deleted_by_search_term_and_sortstring_and_id | ||
+ | * navroot_candidates_by_sortstring_and_id | ||
+ | * navroot_candidates_by_search_term_and_sortstring_and_id | ||
+ | * data_protos_by_sortstring_and_id | ||
+ | * data_protos_by_search_term_and_sortstring_and_id |