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": [],
  "result": {
    "rows": [
      {
        "key": [
          "12532072-0d76-4457-8cf8-7847d0470738",
          "4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
        ],
        "value": null
      },
      {
        "key": [
          "12532072-0d76-4457-8cf8-7847d0470738",
          "7e3e7a96-6ea7-4dc7-a58a-1c781ae35e7b"
        ],
        "value": null
      },
      {
        "key": [
          "12532072-0d76-4457-8cf8-7847d0470738",
          "89e74e40-b0ef-4bc3-8e89-a43a43763087"
        ],
        "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.

For newcomers: In 90% of use cases, the "by_proto_and_design_element_and_value_and_sortstring_and_id" view fits best.

Protogrid Standard Views

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 “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": [],
  "result": {
    "next_card_key": [
      "51b97f49-3262-4339-a8c7-2e8166887761"
    ],
    "rows": [
      {
        "key": [
          "4d523d95-31dd-4cb3-b60a-c974404e4ffd"
        ],
        "value": null
      },
      ...
    ]
  }
}

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

Please note that the “include_cards” parameter has a high cost in terms of performance. We therefore recommend using this functionality very economically, i.e. on as few view rows as possible.

Example respond (be aware, that this Card is a System Card and therefore looks different to the typical Cards):

{
    "errors": [],
    "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"
                ],
                "value": null
            },
           ...
        ]
    }
}

Overall Views With Filtering/Sorting

by_sortstring_and_id

by_design_element_and_sortstring_and_id

by_design_element_and_value_and_sortstring_and_id

This view contains all non-deleted and non-hidden Cards by design_element, date and id. Therefore the key is composed of the key of the design element, the value of the design element, the Card sorting string and the Card key. Example:

["234486c7-939f-49f4-88b2-6fd51369a1d9", "Basic Toilet 2016 ", "Basic Toilet 2016 ", "d81047c2-0d92-48ee-a352-f0c8d4e63b2b"]

The value is null.

Example request to get all Cards, where the name (in my example having with fieldkey “816950eb-1b70-41e2-89f5-5400f9636345”) starts with “n” or “o”:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_design_element_and_value_and_sortstring_and_id?start_key=["816950eb-1b70-41e2-89f5-5400f9636345","n",null,null]&end_key=["816950eb-1b70-41e2-89f5-5400f9636345","m",{},{}]

Example response:

{
    "errors": [],
    "result": {
        "rows": [
            {
                "key": [
                    "816950eb-1b70-41e2-89f5-5400f9636345",
                    "night knight PRO",
                    "night knight PRO",
                    "9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9"
                ],
                "value": null
            },
            {
                "key": [
                    "816950eb-1b70-41e2-89f5-5400f9636345",
                    "nightTable 2.0",
                    "nightTable 2.0 - furniture",
                    "f6e2f9c9-e061-46f4-ab8f-a2594c2b38ae"
                ],
                "value": null
            }
        ]
    }
}

Proto Specific Views

by_proto_and_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 “12532072-0d76-4457-8cf8-7847d0470738”:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_sortstring_and_id?start_key=["12532072-0d76-4457-8cf8-7847d0470738",null,null]&end_key=["12532072-0d76-4457-8cf8-7847d0470738",{},{}]

We use “null” and “{}” as boundaries for the Card key.

Example respond:

{
    "errors": [],
    "result": {
        "rows": [
            {
                "key": [
                    "12532072-0d76-4457-8cf8-7847d0470738",
                    "CWH ONE",
                    "4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
                ],
                "value": null
            },
            ...
        ]
    }
}

by_proto_and_design_element_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, date and id. Therefore the keys is composed of the Proto key, the fieldkey of the design element, the value of the design element, the Card sorting string and the Card key. Example:

["9c2bdd7d-05bd-4d16-8339-11116e737b3a", "&&created", "2016-09-17T20:47:52", "398f0b4c-cbb9-42c9-b4e0-e5c2e7913ec5"]

The value is null. You typically want to use this view to query on system fields such as “&&created” or “&&shortname”, which are available on all Protos.

Example Request to find all Cards based on Proto “12532072-0d76-4457-8cf8-7847d0470738” whos price (“ed2c109d-a825-4b97-a0bb-31c13185408d”) lies between 400 and 500:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/by_proto_and_design_element_and_value_and_sortstring_and_id?start_key=["12532072-0d76-4457-8cf8-7847d0470738","ed2c109d-a825-4b97-a0bb-31c13185408d","400",null,null]&end_key=["12532072-0d76-4457-8cf8-7847d0470738","ed2c109d-a825-4b97-a0bb-31c13185408d","500",{},{}]

Example response:

{
    "errors": [],
    "result": {
        "rows": [
            {
                "key": [
                    "12532072-0d76-4457-8cf8-7847d0470738",
                    "ed2c109d-a825-4b97-a0bb-31c13185408d",
                    "449",
                    "CWH ONE - toilet",
                    "4bcbdb7f-89c3-4640-b04e-3bd468df7c57"
                ],
                "value": null
            },
            {
                "key": [
                    "12532072-0d76-4457-8cf8-7847d0470738",
                    "ed2c109d-a825-4b97-a0bb-31c13185408d",
                    "499",
                    "ForestFire 2016 - lawn mover",
                    "e086c668-500b-4acf-982c-df4f3be65a6b"
                ],
                "value": null
            }
        ]
    }
}

Views for Deleted Cards

deleted_by_sortstring_and_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_sortstring_and_id".

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 "by_design_element_and_sortstring_and_id".

deleted_by_design_element_and_value_and_sortstring_and_id

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 "by_design_element_and_value_and_sortstring_and_id".

Views for Navigation in Relational Tree (Up / Down)

This view contains all Cards by id. The value contains the related keys.

Example request to find all Cards related to the Card “234486c7-939f-49f4-88b2-6fd51369a1d9”:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/related_keys_by_id?keys=[["234486c7-939f-49f4-88b2-6fd51369a1d9"]]

Example response:

{
    "errors": [],
    "result": {
        "rows": [
            {
                "key": [
                    "234486c7-939f-49f4-88b2-6fd51369a1d9"
                ],
                "value": [
                    [
                        "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e",
                        "_users"
                    ],
                    [
                        "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e",
                        "_users"
                    ],
                    [
                        "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e",
                        "_users"
                    ],
                    [
                        "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e",
                        "_users"
                    ],
                    [
                        "6ab4c76c-07a3-4edd-99aa-c61923866020",
                        "_users"
                    ],
                    [
                        "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e",
                        "_users"
                    ],
                    [
                        "system_and_support",
                        "_users"
                    ],
                    [
                        "09cfa5cd-d34e-4afc-f548-3903d26e763e",
                        ""
                    ],
                    [
                        "ce074230-da21-4492-e39b-4c64fb74c1b8",
                        ""
                    ]
                ]
            }
        ]
    }
}

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 “626f04f7-179d-40d7-99f0-9e54343abf98”:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/relating_cards_by_related_key_and_id?start_key=["626f04f7-179d-40d7-99f0-9e54343abf98",null]&end_key=["626f04f7-179d-40d7-99f0-9e54343abf98",{}]

Example response:

{
    "errors": [],
    "result": {
        "rows": [
            {
                "key": [
                    "626f04f7-179d-40d7-99f0-9e54343abf98",
                    "00ded64d-5e1b-42a1-a61e-f8e46c0c552a"
                ],
                "value": null
            },
            {
                "key": [
                    "626f04f7-179d-40d7-99f0-9e54343abf98",
                    "50a9098b-bd4e-47fe-9e99-7d8f1d43517a"
                ],
                "value": null
            },
            {
                "key": [
                    "626f04f7-179d-40d7-99f0-9e54343abf98",
                    "5d068708-9546-4536-94c6-da27b6a909b2"
                ],
                "value": null
            },
            {
                "key": [
                    "626f04f7-179d-40d7-99f0-9e54343abf98",
                    "fa6f178c-a398-4852-a3b3-7e66978c9a65"
                ],
                "value": null
            },
            {
                "key": [
                    "626f04f7-179d-40d7-99f0-9e54343abf98",
                    "fbf79fc6-2da1-41f2-9954-1606dbe3fa01"
                ],
                "value": null
            }
        ]
    }
}

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.

Example request to get card with key “5f12ccf6-9de0-4796-d366-106e4b7b8af9”:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/tableview_data_by_id?keys=[["5f12ccf6-9de0-4796-d366-106e4b7b8af9"]]

Example response:

{
    "errors": [],
    "result": {
        "rows": [
            {
                "key": [
                    "5f12ccf6-9de0-4796-d366-106e4b7b8af9"
                ],
                "value": {
                    "#": [
                        "5f12ccf6-9de0-4796-d366-106e4b7b8af9"
                    ],
                    "&&created": [
                        "2016-03-23T13:19:17"
                    ],
                    "&&creator": [
                        "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e",
                        "_users"
                    ],
                    "&&modified": [
                        "2016-03-23T13:38:19"
                    ],
                    "&&modifier": [
                        "a77b8462-ec5f-4b8e-9bc3-29fe8784c69e",
                        "_users"
                    ],
                    "&&proto_key": [
                        "&&multilanguageProto"
                    ],
                    "&&shortname": [
                        {
                            "de": "Card: 5f12ccf6-9de0-4796-d366-106e4b7b8af9",
                            "en": "Card: 5f12ccf6-9de0-4796-d366-106e4b7b8af9"
                        }
                    ],
                    "de": [
                        ""
                    ],
                    "en": [
                        ""
                    ]
                }
            }
        ]
    }
}

shortname_objects_by_id

This view contains all Cards which contain shortname data by id. The value contains the shortnames by language.

Example request to get the shortnames of the Card with key “a0e6717f-c613-404a-bc08-a090311c651c”:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/shortname_objects_by_id?keys=[["a0e6717f-c613-404a-bc08-a090311c651c"]]

Example response:

{
    "errors": [],
    "result": {
        "rows": [
            {
                "key": [
                    "a0e6717f-c613-404a-bc08-a090311c651c"
                ],
                "value": {
                    "de": "Priscilla Molesworth - wishes an offer",
                    "en": "Priscilla Molesworth - wishes an offer"
                }
            }
        ]
    }
}

Views of Dedicated Search Dialog Boxes

It is also possible to access the views of dedicated Search Dialog Box from the JSON API. Just use the Card ID of the Search Dialog Box as view name.

Hint: For straight forward API usage in most cases it is recommended to use Search Dialog Boxes in “Simple Keys in JSON API only” display mode.

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/less than option enabled), the time portion is left as it is (example: “2021-11-11T22:22:00.000Z”).

Example Request:

https://example.protogrid.com/api/v2/apps/produktekatalog/views/869a18bf-2fb6-4d6d-afe4-3b6283f35ba3

The key depends on the individually configured Filter Fields for the acessed Search Dialog Box.

Change Log

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

Standard Views Decommissioned With Version 2.2.1

  • by_design_element_and_value_and_id
  • 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

Adjustments to Views With Version 2.2.2

  1. All views: If a view is requested with the “descending” parameter set to true “start_key” and “end_key” must now be exchanged.
  2. All views: All string values as well as sortstrings are now cut off after 300 characters.
  3. All views: The separator between human readable values and keys is now “\u0009” instead of “\u9999”.
  4. All views: The second last column “sortstring” is now indexed in a shorter manner: “<SORTSTRING>” instead of “<PROTO KEY>\u9999<SORTSTRING>\u9999<CARD KEY>”
  5. 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.
  6. Dedicated Search Boxes: Datetime Fields in Dedicated Search Boxes are now 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/less than option enabled), the time portion is left as it is (example: “2021-11-11T22:22:00.000Z”).
  7. Dedicated Search Boxes with “sortable” display mode: Columns are now indexed in a shorter manner:
    • For Relation/Tag Field values: “< SORTSTRING >\u0009<KEY>” instead of “<SORTSTRING>\u9999<KEY>\u9999<KEY>”
    • For other field values: “<VALUE>” instead of “\u9999<VALUE>\u9999<VALUE>”
    • Note: It is anyway recommended to use Search Dialog Boxes with display mode “Simple Keys in JSON API only” (i. e. non-sortable).
  8. In views “by_design_element_and_sortstring_and_id”, “by_proto_and_design_element_and_sortstring_and_id” and “deleted_by_design_element_and_sortstring_and_id” the design element's sortstrings are now indexed in a shorter manner:
    • For Relation/Tag Field values: “< SORTSTRING >\u0009<KEY>” instead of “<SORTSTRING>\u9999<KEY>\u9999<KEY>”
    • For other field values: “<VALUE>” instead of “\u9999<VALUE>\u9999<VALUE>”
    • Note: If you don't explicitly need sorting by design element value is anyway recommended to use the views “by_design_element_and_value_and_sortstring_and_id”, by_proto_and_design_element_and_value_and_sortstring_and_id“” or “deleted_by_design_element_and_value_and_sortstring_and_id”.
  9. In views “by_design_element_and_sortstring_and_id”, “by_proto_and_design_element_and_sortstring_and_id” and “deleted_by_design_element_and_sortstring_and_id” there is a new column for the Card's sortstring after the design element's sortstring. Example:
    • View columns of “by_design_element_and_sortstring_and_id” before: [“816950eb-1b70-41e2-89f5-5400f9636345”, “nightTable 2.0”, “9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9”]
    • View columns of by_design_element_and_sortstring_and_id“” now: [“816950eb-1b70-41e2-89f5-5400f9636345”, “nightTable 2.0”, “nightTable 2.0 - furniture”, “9a5f37ab-30a7-4c91-b99f-f573a1c7d1b9”]

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
Print/export