This section lists the different API endpoints you can use to access or update Protogrid data. The respective http method is defined as [METHOD] following the endpoint in this documentation.
Every request to such an API endpoint returns a JSON object. The returned JSON object always contains an error and a result object. If the request was successful, the result object contains the requested or updated data. When the request fails, the errors object contains the error messages which occurred when trying to execute the request.
{ "errors": [], "protogrid_environment_version": "1.3.9", "result":{ "key": {…}, "key": […], "key": "data" } }
{ "errors": [ { … }, { … } ], "protogrid_environment_version": "1.3.9", "result": {} }
In Protogrid there exist different types of fields such as numbers, text or dates.
Protogrid always uses ISO 8601 standard in UTC timezone for storing date time values.
The Protogrid JSON API offers the following API endpoints:
[GET] Returns a list of all Applications to which the authenticated user has access to.
Example request:
https://example.protogrid.com/api/v2/apps
Example response:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result":[ { "app_id": "app_example_id", "description": "Example App", "logo_url": "", "theme_color": "blue-dark", "title": "Example App ", "url": "/example", "url_name": "example" }, { "app_id": "appID", "description": "Your awesome app", … }, … ] }
[GET] Returns basic information about one Application.
Example request:
https://example.protogrid.com/api/v2/apps/example
Example response:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result": { "app_id": "appID", "description": "Example App", "logo_url": "", "theme_color": "blue-dark", "title": "Example App ", "url": "/example", "url_name": "example" } }
[GET] Returns a list of all view names in this Application. Details on what views are supported, see all available views.
Example request:
https://example.protogrid.com/api/v2/apps/example/views
Example response:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result": { "views": [ {"view_name": "examples_by_id"}, {…} ] } }
Most of the API endpoints except you to specify App or Card IDs. At the time at which this data is requested, these ids therefore already need to be known. It is therefore necessary to have convenient ways of asking Protogrid about what ids are available based on different search criteria. Database views can be used to acquire collections of data based on sorting and filtering URL parameters.
[GET] Returns all the entries in the specified view. Please note that URL parameters must be URI encoded. URL Parameter:
Please note:
Details: For more details about the URL parameters see the CouchDB documentation.
Full list of views can be found here.
Example request:
https://example.protogrid.com/api/v2/apps/example/views/example_view?start_key=["example_proto_key",null]&end_key=["example_proto_key",{}]&page_number=1&limit=2&descending=false
The URL parameters need to be URI encoded. So from the example above the start_key parameter would look like
start_key= %5B%22example_proto_key%22%2Cnull%5D
Example response:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result": { "next_card_key": "key", "rows": [ {"key": "example_document_key"}, {…} ] } }
[POST] Creates a new Card. It is necessary to specify a 'proto_key' denoting the Proto on which the new Card will be based. Initial values for the 'design_elements' can be sent along. Mandatory design elements must always be set. If a Card ID of an existing card is specified in the property '_id', Protogrid updates this Card with the provided data. If an array of Card objects is supplied in the POST request body, all of them will be created/updated as a bulk operation. Note that in bulk operation either all or none of the passed Cards will be saved. For example, out of 100 Cards, none will be saved if a single Card has caused validation errors. As response this endpoint returns a list of all created/updated Cards.
Example request:
https://example.protogrid.com/api/v2/apps/example/cards
In the POST request body, a JSON object needs to be sent as shown in the following example:
{ "proto_key": "some_proto_key", "design_elements": [ { "definition_key": "example_design_element_key", "value": "example_value" }, … ] }
Example response:
{ "errors": [], "messages": [], "protogrid_environment_version": "2.1.5", "result": { "_id": "some_card_id", "_rev": "some_rev_id", "denormalized": {…}, "design_elements": {…}, … } }
Deprecated functionalities:
[GET] Returns a specific Card identified by 'card_key'.
[DELETE] Logically deletes a specific Card identified by 'card_key'. Please note that the deleted Card will be still available, either through the API or the UI using the trash. The return value contains the newly deleted Card.
[POST] Updates an existing Card identified by 'card_key'. If the '_id' property is set in the JSON, it needs to match the 'card_key'. In addition, the 'proto_key' must match that of the existing Card.
Example request:
https://example.protogrid.com/api/v2/apps/example/cards/some_card_id
In the POST request body, a JSON object needs to be sent as shown in the following example:
{ "_id": "some_card_id", "proto_key": "some_proto_key", "design_elements": [ { "definition_key": "example_design_element_key", "value": "example_value" }, … ] }
Example response:
{ "errors": [], "messages": [], "protogrid_environment_version": "2.1.5", "result": { "_id": "some_card_id", "_rev": "some_rev_id", "denormalized": {…}, "design_elements": {…}, … } }
[GET] Returns the attachment identified by 'file_name' of a Card identified by 'card_key'.
[PUT] Uploads the Form Data attachment with name 'attachment-upload' to the specified Card. If this Card already has an attachment with the specified file name, the existing attachment is replaced by the uploaded one.
Example GET request:
https://example.protogrid.com/api/v2/apps/example_app/cards/89e74e40-b0ef-4bc3-8e89-a43a43763087/attachments/Bildschirmfoto%202021-01-22%20um%2014.11.15.png
Example code for PUT request:
var HOST = "https://example.protogrid.com/"; var APP_NAME = "example_app"; var CARD_KEY = "89e74e40-b0ef-4bc3-8e89-a43a43763087"; function uploadFile(file, progressCallback, successCallback) { function createFormData(file) { var data = new FormData(); data.append("Content-Type", file.type); data.append("attachment-upload", file); return data; } var attachment_base_url = HOST + "api/v2/apps/" + APP_NAME + "/cards/" + CARD_KEY + "/attachments/"; var initial_file_name = file.name; var xhr = new XMLHttpRequest(); xhr.open("PUT", attachment_base_url + initial_file_name, true); xhr.upload.addEventListener("progress", function(progress_event) { var progress = progress_event.loaded / progress_event.total * 66; // We want the progress bar to show "loading" until the server response is back. progressCallback(progress); }); xhr.addEventListener("load", function() { if (xhr.status == 200) { var saved_filename = initial_file_name; if (xhr.response && typeof(xhr.response) === 'string' && xhr.response !== '') { var response = JSON.parse(xhr.response); if (response && typeof(response) === 'object' && response.result && typeof(response.result) === 'object' && response.result.file_name && typeof(response.result.file_name) === 'string' && response.result.file_name !== '') { saved_filename = response.result.file_name; } } progressCallback(100); successCallback({ url: attachment_base_url + saved_filename }); } }); xhr.send(createFormData(file)); }
The corresponding Form Data:
------WebKitFormBoundarya04hDppsnTo2uPOR Content-Disposition: form-data; name="Content-Type" image/png ------WebKitFormBoundarya04hDppsnTo2uPOR Content-Disposition: form-data; name="attachment-upload"; filename="Bildschirmfoto 2021-01-22 um 14.11.15.png" Content-Type: image/png ------WebKitFormBoundarya04hDppsnTo2uPOR--
Example response after successful attachment upload:
{ "errors": [], "result": { "file_name": "Bildschirmfoto_2021-01-22_um_14.11.15.png" } }
[GET] Returns a list of all protos of the specified application.
The following URL parameter can be used for paging:
The returned result contains a key “next_card_key” whose value is the next key not returned in this answer.
Example request:
https://example.protogrid.com/api/v2/apps/example/protos?limit=1
Example result:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result": { "next_card_key": "NextProtoKey" "protos": [ {"key": "ExampleProtoKey"} ] } }
[GET] Returns detailed information about the specified Proto.
Example request:
https://example.protogrid.com/api/v2/apps/example/protos/example_proto_key
Example result:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result": { "key": "example_proto_key", "shortname": "Example Proto", "field_and_widget_keys": [ { "allow_new_cards": true, "cardinality_setting": 2, "couchdb_viewname": "", "disable_label": false, "display_priority": 7, "element_type": "Relation", "grid_size_setting": 0, "help_text": "", "hidden": false, "label_multilanguage_key": "&&mlkey_design_elements", "multiple_values_setting": 1, "name": "card_design_elements", "parent_application_setting": "", "parent_entity_proto_setting": "DesignElementDefinition", "requirement_setting": 0, "show_card_type": true, "show_created_setting": false, "show_creator_setting": false, "show_modified_setting": false, "show_modifier_setting": false, "show_short_name_setting": false, "show_to_users": 0, "user_enabled_setting": 0, "value": [ "design_element_key_1 ", "design_element_key_2", … ], "value_type": "key" }, {…}, … ] } }
[GET] Returns the keys for all Cards based on the specified proto.
The following URL parameter can be used for paging:
The returned result contains a key “next_card_key” whose value is the next key not returned in this answer.
Example request:
https://example.protogrid.com/api/v2/apps/example/protos/example_proto/card-keys?limit=1
Example result:
{ "errors": [], "protogrid_environment_version": "1.3.9", "result": [ "card_keys":[ "ExampleProtoKey", "ExampleSortstring", "ExampleCardKey" ], "next_card_key": "NextCardKey" ] }
[POST] Send an email
To be able to use this endpoint, the SMTP mail server of your organization must first be configured as the designated mail relay server in your Environment. If this has not been done yet, please contact Protogrid Support.
Protogrid will fist try to establish a TLS session to the specified mail relay server and authenticate using the supplied credentials. If TLS is not available it will try to connect using SSL. Finally if SSL is not available the function tries to connect using unsecured SMTP protocol.
The mail will be sent according to the currently logged in user (mail address specified in user profile and the field “SMTP Server Password” if requested by the mailserver).
The following JSON data fields can be used:
Attachments and inline images must already reside inside Protogrid, each attached to a Card. The logged in user must have read access to this Card(s). Attachments and inline images are specified using an Object with the following structure:
{ "card_id": "<ID of the Card on which the attachment or image resides>", "file_name": "<Name of the file as it is listed in the Card specified above>" }
By default, users can send a mail to up to 10 recipients. This limit can be increased via the roles assigned to the users using the field “Allowed Number of Recipients per Mail Sent” on each Role Definition. However, a mail never can be sent to more than 500 recipients.
The returned result will include a success message or details about the particular error.
Example client-side jQuery request:
$.post({ url: "https://example.protogrid.com/api/v2/apps/example/mailsend", data: JSON.stringify({ "to": ["Tester 1️⃣ <test1@ategra.ch>", "Tester 2️⃣ <test2@ategra.ch>"], "cc": ["Tester 3️⃣ <test3@ategra.ch>", "Tester 4️⃣ <test4@ategra.ch>"], "bcc": ["Tester 5️⃣ <test5@ategra.ch>", "Tester 6️⃣ <test6@ategra.ch>"], "reply_to": ["Tester 7️⃣ <test7@ategra.ch>", "Tester 8️⃣ <test8@ategra.ch>"], "from": "Tester 0️⃣ <test0@ategra.ch>", "subject": "Test Email with Emojis 👍", "body_text_plain": "This is a test message in plain text 😎.", "body_text_html": "This is a <b>test</b> message 🤖.<br><br>Please check if the message is displayed correctly using several different mail clients or tools like Mailtrap (<a href='https://mailtrap.io'>link</a>).<br><br><img src='cid:logo.png'></img>", "inline_images": [ {"card_id": "ffc3a027-2fed-45f8-8aa8-adec18a90439", "file_name": "logo.png"} ], "attachments": [ {"card_id": "ffc3a027-2fed-45f8-8aa8-adec18a90439", "file_name": "Protogrid_Quickstart_Tutorial.pdf"} ] }), contentType: 'application/json; charset=utf-8' }).done(function (response) { alert("Data: " + JSON.stringify(response)); });
As a response you receive a JSON with the following structure:
Example response:
{ "errors": [], "messages": [ "Couldn't send the mail using a secure TlS communication channel. Trying SSL instead.", "Couldn't send the mail an SSL communication channel. Trying without encryption." ], "result": { "external@recipient.ch": [ 554, "5.7.1 <external@recipient.ch>: Relay access denied" ] } }