This is an old revision of the document!
Table of Contents
JSON API Database Views
A Database View can be seen as a table with two columns. The first column is called 'key', the second one is called 'value'. The keys have to be unique. A lookup to a view always expects a key, several keys or a range of keys. The response of a lookup consists of all requested keys together with their values. Example for respond:
{
"errors": [],
"protogrid_environment_version": "1.4.10",
"result": {
"rows": [
{
"key": [
"12532072-0d76-4457-8cf8-7847d0470738",
"4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
],
"shortname": "CWH ONE",
"value": null
},
{
"key": [
"12532072-0d76-4457-8cf8-7847d0470738",
"7e3e7a96-6ea7-4dc7-a58a-1c781ae35e7b"
],
"shortname": "DirtKiller 64 - washing machines",
"value": null
},
{
"key": [
"12532072-0d76-4457-8cf8-7847d0470738",
"89e74e40-b0ef-4bc3-8e89-a43a43763087"
],
"shortname": "SuperCleaner 2000 - washing machines",
"value": null
}
]
}
}
For details about listings / views and how to request it, please see section about view endpoints. Please note that all views have the Card id as the last key component due to how Protogrid is implemented on top of CouchDB. In most cases it is useful to specify the start_key and end_key URL parameters with null and {} (empty object) as their last element. This will give all keys matching the other specified keys.
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 “next_card_key” of the previous page as startkey.
Example request to get the first 5 Cards with ids which are lexicographically between “4d523d95-31dd-4cb3-b60a-c974404e4ffd” and “5f09e616-9883-41cb-8986-a0f2ec690971”:
https://example.protogrid.com/api/v2/apps/produktekatalog/views/all_by_id?start_key=["4d523d95-31dd-4cb3-b60a-c974404e4ffd"]&end_key=["5f09e616-9883-41cb-8986-a0f2ec690971"]&limit=5
Example respond:
{
"errors": [],
"protogrid_environment_version": "1.4.10",
"result": {
"next_card_key": [
"51b97f49-3262-4339-a8c7-2e8166887761"
],
"rows": [
{
"key": [
"4d523d95-31dd-4cb3-b60a-c974404e4ffd"
],
"shortname": {},
"value": null
},
...
]
}
}
by_id_and_value
This view contains all Cards. The keys is the Card ID (e.g. “35d38163-bcf2-409a-94b5-dc314ce8ade8”) and the value contains the raw Card. This view is a good choice if you already know the IDs of the desired cards, but still need the content of the cards.
Be aware: This is one of the very few views, where the key is NOT surrounded by “[ … ]”!
Example Request to get the cards with the IDs “4bcbdb7f-89c3-4640-b04e-3bd468df7c57”, “396662ac-2b73-434e-ac73-66812f5b3ab8”,“398f0b4c-cbb9-42c9-b4e0-e5c2e7913ec5” ,“45d1be23-3b2f-4edc-96c2-ab903c3b2554”:
https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_id_and_value?keys=["4bcbdb7f-89c3-4640-b04e-3bd468df7c57", "396662ac-2b73-434e-ac73-66812f5b3ab8","398f0b4c-cbb9-42c9-b4e0-e5c2e7913ec5" ,"45d1be23-3b2f-4edc-96c2-ab903c3b2554"]
Example respond:
{
"errors": [],
"protogrid_environment_version": "1.4.14",
"result": {
"rows": [
{
"key": "4bcbdb7f-89c3-4640-b04e-3bd468df7c57",
"shortname": "CWH ONE",
"value": {
"_id": "4bcbdb7f-89c3-4640-b04e-3bd468df7c57",
"_rev": "7-a9637cc70544647e5c3b62135b70800f",
"denormalized": {
"12532072-0d76-4457-8cf8-7847d0470738": {
"displayable_type": {
"de": "Daten-Proto",
"en": "Data Proto"
},
"shortname": {
"de": "Proto:Produkt",
"en": "Proto:product"
}
},
...
},
"design_elements": [
{
"definition_key": "d518ee80-49b7-49bb-b6c8-fe8ced9c57f6",
"value": "201"
},
...
],
"get_shortname": {},
"last_healed": "2016-07-06T14:17:13",
"modification_log": [
{
"time": "2016-09-17T20:03:57",
"user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e"
},
...
],
"proto_key": "12532072-0d76-4457-8cf8-7847d0470738",
"reader_role_key": "",
"set_element_value": {}
}
},
{
"key": "396662ac-2b73-434e-ac73-66812f5b3ab8",
...
},
{
"key": "398f0b4c-cbb9-42c9-b4e0-e5c2e7913ec5",
...
},
{
"key": "45d1be23-3b2f-4edc-96c2-ab903c3b2554",
...
}
]
}
}
all_protos_by_id
This view contains all Protos by id. The value contains shortname and a list of design_elements.
Example request to get the first 5 protos:
https://example.protogrid.com/api/v2/apps/produktekatalog/views/all_protos_by_id?limit=5
Example respond:
{
"errors": [],
"protogrid_environment_version": "1.4.14",
"result": {
"next_card_key": "&&protosTableViewProto",
"rows": [
{
"key": "&&allTableViewProto",
"shortname": "Proto:All Cards By ID",
"value": {
"design_elements": [
"name",
"plural_name",
"theme_color",
"enable_attachments",
"enable_filtering_for_id",
"script_library",
"editor_role",
"allow_editing_cards_to_users",
"show_cards_to_users",
"creator_role",
"automatically_created_tableview_proto",
"comment",
"card_design_elements",
"cards_based_on_this"
],
"shortname": {
"en": "Proto:All Cards 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.
Example request to get all IDs with the Cards content (with flag “include_cards=true”):
https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_id?start_key=[null]&end_key=[{}]&include_cards=true
Example respond (be aware, that this Card is a System Card and therefore looks different to the typical Cards):
{
"errors": [],
"protogrid_environment_version": "1.4.14",
"result": {
"next_card_key": [
"&&logTableViewDefinition"
],
"rows": [
{
"doc": {
"_id": "&&adminMenuDefinition",
"_rev": "36-511c0128517aac0c5f4d3dbc22d6451a",
"definition_type": "Menu",
"denormalized": {
"&&adminMenuDefinition": {
"displayable_type": {
"en": "MenuDefinition"
},
"shortname": {
"en": "Menu:Administration"
}
},
"ac722839-acc7-4683-e9cf-0d2eb3137575": {
"displayable_type": {
"de": "DynamicCard",
"en": "DynamicCard"
},
"shortname": {
"de": "Schritttypen",
"en": "types of steps"
}
},
...
},
"design_elements": [
{
"disable_label": false,
"display_priority": 10,
"element_type": "MultilanguageText",
"grid_size_setting": 0,
"help_text": "",
"hidden": false,
"label_multilanguage_key": "&&mlkey_menu_title_key",
"list_priority": 0,
"multiple_values_setting": 0,
"name": "title",
"requirement_setting": 0,
"show_to_users": 0,
"user_enabled_setting": 0,
"value": "&&mlkey_admin_menu_header",
"value_type": "key"
},
{
"allow_new_cards": false,
"cardinality_setting": 2,
"couchdb_viewname": "navroot_candidates",
"disable_label": false,
"display_priority": 10,
"element_type": "Relation",
"grid_size_setting": 0,
"help_text": "",
"hidden": false,
"label_multilanguage_key": "&&mlkey_menu_entries",
"multiple_values_setting": 1,
"name": "menu_entries",
"parent_application_setting": "",
"parent_entity_proto_setting": "",
"requirement_setting": 0,
"show_card_type": false,
"show_created_setting": false,
"show_creator_setting": false,
"show_modified_setting": false,
"show_modifier_setting": false,
"show_short_name_setting": true,
"show_to_users": 0,
"user_enabled_setting": 0,
"value": [
"&&allTableViewCard",
"&&logTableViewCard",
"&&trashTableViewCard",
"&&importExportCard",
"ac722839-acc7-4683-e9cf-0d2eb3137575",
"502ece2e-0bd5-43c6-dd26-2bc368261ee0"
],
"value_type": "key"
}
],
"get_shortname": {},
"hidden": false,
"last_healed": "2017-04-14T06:44:52",
"modification_log": [
{
"time": "2016-03-23T12:11:47",
"user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e"
},
...
],
"reader_role_key": "",
"set_element_value": {},
"title_multilanguage_key": "&&mlkey_menu_definition_key",
"user_creatable": true
},
"key": [
"&&adminMenuDefinition"
],
"shortname": "Menu:Administration",
"value": null
},
...
]
}
}
by_id_and_value
This view contains all non-deleted and non-hidden Cards. The value is raw Card. In typical use, you want to use this view to load your Cards, since you do not want to load Cards which are deleted or hidden by accident.
Be aware: This is one of the very few views, where the key is NOT surrounded by “[ … ]”!
Example request to get the Cards whose ID is within the range “a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c” to “a5a8815d-9cff-4489-9e21-6f54163408ee”:
https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_id_and_value?start_key="a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c"&end_key="a5a8815d-9cff-4489-9e21-6f54163408ee"
Example respond (do not be confused by the special content of the Card: It is a Multilanguage Card):
{
"errors": [],
"protogrid_environment_version": "1.4.14",
"result": {
"rows": [
{
"key": "a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c",
"shortname": "Product Catalog",
"value": {
"_id": "a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c",
"_rev": "4-001d21026ea44eccea11cabe45358dbf",
"denormalized": {
"&&multilanguageProto": {
"allow_editing_cards_to_users": 0,
"creator_role": "",
"editor_role": "",
"show_cards_to_users": 0
},
"a3c8b1b5-ea36-4ae0-f1bd-5366543ae36c": {
"displayable_type": {
"de": "DynamicCard",
"en": "DynamicCard"
},
"shortname": {
"de": "Product Catalog",
"en": "Product Catalog"
}
}
},
"design_elements": [
{
"definition_key": "en",
"value": "Product Catalog"
},
{
"definition_key": "de",
"value": "Produktekatalog"
}
],
"get_design_element": {},
"get_design_element_properties": {},
"get_key": {},
"get_proto_key": {},
"get_shortname": {},
"get_type": {},
"get_value": {},
"last_healed": "2016-02-17T05:31:30",
"modification_log": [
{
"time": "2016-03-23T12:11:47",
"user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e"
},
{
"time": "2016-03-23T12:13:11",
"user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e"
},
{
"time": "2016-03-23T12:16:46",
"user": "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e"
},
{
"time": "2016-03-23T18:02:59",
"user": "6ab4c76c-07a3-4edd-99aa-c61923866020"
}
],
"proto_key": "&&multilanguageProto",
"reader_role_key": "",
"set_design_element_value": {},
"set_element_value": {}
}
},
{
"key": "a5a8815d-9cff-4489-9e21-6f54163408ee",
...
}
]
}
}
deleted_by_id
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_id".
by_proto_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 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 “12532072-0d76-4457-8cf8-7847d0470738”:
https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_id?start_key=["12532072-0d76-4457-8cf8-7847d0470738", null]&end_key=["12532072-0d76-4457-8cf8-7847d0470738", {}]
We use “null” and “{}” as boundaries for the Card key.
Example respond:
{
"errors": [],
"protogrid_environment_version": "1.4.14",
"result": {
"rows": [
{
"key": [
"12532072-0d76-4457-8cf8-7847d0470738",
"4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
],
"shortname": "CWH ONE",
"value": null
},
...
]
}
}
Out of this, you now know the Card keys of all Cards based on this Proto. To get the content of the Cards, you need to get the second part of every key, read it into an array and the request all Cards within the array using the view by_id_and_value.
by_proto_and_shortname_and_id
This View contains all non-deleted and non-hidden Cards with corresponding Proto and shortname by id. This means the key is composed of the Proto key, the shortname and the Card ID. Example:
["12532072-0d76-4457-8cf8-7847d0470738", "SuperCleaner 2000 - washing machines", "89e74e40-b0ef-4bc3-8e89-a43a43763087"]
The value is null.
$$$ Example: is it possible to ask for shortname? Otherwise: Ask for all Cards, get the shortnames (e.g. for displaying)
by_search_term_and_id
This view contains Cards for a certain search term by id. The key is composed of the search term and the Card key. Search term means a specific string, for which you want to find all Cards containing this string. Example:
["behavior", "1475e62a-47d7-4a29-98c2-c89f50edd497"]
Value is null.
deleted_by_search_term_and_id
All deleted Cards for a certain serach term by id. Value is null.
by_proto_and_search_term_and_id
All Protos for a certain search term by id. Value is null.
by_design_element_and_value_and_id
All Cards by design_element, date and id. Value is null.
deleted_by_design_element_and_value_and_id
All deleted Cards by design_element, date and id. Value is null.
by_proto_and_design_element_and_value_and_id
All Cards by underlying Proto, design_element, date and id. Value is null.
relational_definitions_by_id_and_related_proto
All relational definitions by related proto and id. Value is null.
data_protos_by_id
All data Protos by id. Value is null.
data_protos_by_search_term_and_id
All data Protos for a certain search term and by id. Value is null.
datetime_field_definitions_by_id
All datetime field definitions by id.
datetime_field_definitions_by_search_term_and_id
All datetime field_definitions for a certain search term by id. Value is null.
related_keys_by_id
All Cards with related keys by id. Value contains the related keys.
by_relating_key
All Cards with the related key by id. Value is null.
tableview_data_by_id
All Cards contained in a tableview by id. Value contains the raw card.
shortname_by_language_objects_by_id
All Cards which contains shortname data by id. Value contains the shortnames by language.
sums_by_proto_and_design_element
Sums over the values of a field for all Cards of a Proto. Depending on the field type, this uses the following functions:
- 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.
sums_by_proto_and_design_element_and_condition
Sums over the values of a field for all Cards of a Proto given a condition from another field. This key requires query keys with four 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 component (3)
Example: What is the sum over all values in the “Total” field in the Proto “Invoice”, given that the relation field “customer” holds the key for “John Smith”?
Depending on the field type, this uses the following functions:
- 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.
