Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
protogrid:api_endpoints [2021-02-11 21:48]
178.193.212.125 [/api/v2/apps/<app_name>/cards]
protogrid:api_endpoints [2021-12-20 15:38] (current)
dru [/api/v2/apps/<app_name>/protos/<proto_key>/card-keys]
Line 7: Line 7:
  
 ==== Example successful response ==== ==== Example successful response ====
-<code json>+<code javascript>
 { {
   "errors": [],    "errors": [], 
Line 20: Line 20:
  
 ==== Example failure response ==== ==== Example failure response ====
-<code json>+<code javascript>
 { {
   "errors": [   "errors": [
Line 55: Line 55:
  
 Example response: Example response:
-<code json>+<code javascript>
 { {
   "errors": [],    "errors": [], 
Line 90: Line 90:
 Example response: Example response:
  
-<code json>+<code javascript>
  
   "errors": [],   "errors": [],
Line 118: Line 118:
 Example response: Example response:
  
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
Line 139: Line 139:
   * end_key: ["proto_key", "column_key", "filter_value", {}], where column_key and filter_value are optional   * end_key: ["proto_key", "column_key", "filter_value", {}], where column_key and filter_value are optional
   * keys: ["key1", "key2", "key3", …], only returns the entries for the specified keys   * keys: ["key1", "key2", "key3", …], only returns the entries for the specified keys
-  * page_number: Set to 1 if on the first page, otherwise 2 +  * page_number: Number of the desired page starting at 0 for the first page. Page length is determined by the 'limit' parameter (counted before filtering for read access rights). 
-  * limit: Accepts a number, which defines how many cards are returned in the result object.+  * limit: Accepts a number, which defines how many Cards are returned at most with the result object. Fewer Cards can be returned if not all Cards are visible due to read acces restrictions.
     * Example: limit=15     * Example: limit=15
     * Default value: 10     * Default value: 10
-  * descending: If set to true the results will be in descending order.+  * descending: If set to true the results will be in descending order. If set to true start_key and end_key must be exchanged.
     * Example: descending=true     * Example: descending=true
     * Default value: False     * Default value: False
Line 149: Line 149:
     * Example: include_cards=true     * Example: include_cards=true
     * Default value: False     * Default value: False
 +    * 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.
 +
          
-Noteyou may only use either keys or start_key and end_key.+Please note: 
 +  * You may only use either "keysor "start_keyand "end_key". 
 +  * Key values must be cut off after 300 characters (e. g. string values and sortstrings) because these values are also cut off in the view index.
  
 Details: For more details about the URL parameters see the [[http://docs.couchdb.org/en/stable/api/ddoc/views.html|CouchDB documentation]]. Details: For more details about the URL parameters see the [[http://docs.couchdb.org/en/stable/api/ddoc/views.html|CouchDB documentation]].
Line 169: Line 173:
 Example response: Example response:
  
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
Line 176: Line 180:
     "next_card_key": "key",     "next_card_key": "key",
     "rows": [     "rows": [
-      {"key": "example_document_key", "shortname": "example_shortname"},+      {"key": "example_document_key"},
       {…}       {…}
     ]     ]
Line 185: Line 189:
 ==== /api/v2/apps/<app_name>/cards ==== ==== /api/v2/apps/<app_name>/cards ====
  
-[POST] Creates a new Card. It is necessary to specify a "proto_keydenoting the Proto on which the new Card will be based. Initial values for the "design_elementscan 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. As response this endpoint returns a list of all created/updated Cards.+[POST] Creates a new Card. It is necessary to specify a 'proto_keydenoting the Proto on which the new Card will be based. Initial values for the 'design_elementscan 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:  Example request: 
Line 192: Line 196:
 </code> </code>
  
-In the POST request body, you need to send a JSON object as shown in the following example:+In the POST request body, a JSON object needs to be sent as shown in the following example:
 <code javascript> <code javascript>
  
   "proto_key": "some_proto_key",   "proto_key": "some_proto_key",
   "design_elements": [   "design_elements": [
-    {"definition_key": "example_design_element_key", "value":"example_value"}, +    { 
-    {}+      "definition_key": "example_design_element_key", 
 +      "value": "example_value" 
 +    }, 
 +    …
   ]   ]
 } }
Line 207: Line 214:
 { {
   "errors": [],   "errors": [],
-  "protogrid_environment_version": "1.3.9", +  "messages": [], 
-  "results": {+  "protogrid_environment_version": "2.1.5", 
 +  "result": {
     "_id": "some_card_id",     "_id": "some_card_id",
     "_rev": "some_rev_id",     "_rev": "some_rev_id",
     "denormalized": {…},     "denormalized": {…},
 +    "design_elements": {…},
     …     …
   }   }
Line 218: Line 227:
  
 Deprecated functionalities: Deprecated functionalities:
-  * Specification of a user-defined card_key for a new Card: In previous versions, in the JSON object it was possible to freely specify the card_key for a new Card. This functionality is deprecated and cannot be used in future releases. In particular if you relied on this feature to insert foreign IDs into Protogrid, we suggest using an additional auxiliary field containing the foreign ID.+  * Specification of a user-defined Card ID for a new Card: In previous versions, it was possible to freely specify the Card ID for a new Card in the '_id' property. This functionality is deprecated and cannot be used in future releases. In particular, instead of relying on this feature to insert foreign IDs into Protogrid, we suggest using an additional auxiliary field containing the foreign ID.
  
 ==== /api/v2/apps/<app_name>/cards/<card_key> ==== ==== /api/v2/apps/<app_name>/cards/<card_key> ====
-[GET] Returns a specific Card identified by card_key.+[GET] Returns a specific Card identified by 'card_key'.
  
-[DELETE] Deletes a specific Card identified by card_key logicallyThe deleted Card will be still available, either through the API or the UI using the Trash under Administration. The return value contains the deleted Card.+[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' field is set in the JSON, it needs to match the card_key. In addition, the proto_key must match that of the existing Card. Otherwise an error is thrown.+[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_keymust match that of the existing Card.
  
 Example request:  Example request: 
Line 232: Line 241:
 </code> </code>
  
-In the body of the POST request, you need to send a JSON object as shown in the following example:+In the POST request body, a JSON object needs to be sent as shown in the following example:
 <code javascript> <code javascript>
 { {
-  "_id": some_card_id, +  "_id": "some_card_id"
-  "proto_key": some_proto_key,+  "proto_key": "some_proto_key",
   "design_elements": [   "design_elements": [
-    {"definition_key": "example_design_element_key", "value": "example_value"}, +    { 
-    {}+      "definition_key": "example_design_element_key", 
 +      "value": "example_value" 
 +    }, 
 +    …
   ]   ]
 } }
Line 247: Line 259:
 { {
   "errors": [],   "errors": [],
-  "protogrid_environment_version": "1.3.9", +  "messages": [], 
-  "results": {+  "protogrid_environment_version": "2.1.5", 
 +  "result": {
     "_id": "some_card_id",     "_id": "some_card_id",
     "_rev": "some_rev_id",     "_rev": "some_rev_id",
     "denormalized": {…},     "denormalized": {…},
 +    "design_elements": {…},
     …     …
   }   }
Line 258: Line 272:
  
 ==== /api/v2/apps/<app_name>/cards/<card_key>/attachments/<file_name> ==== ==== /api/v2/apps/<app_name>/cards/<card_key>/attachments/<file_name> ====
-[GET] Returns the attachment identified by attachment_key.+[GET] Returns the attachment identified by 'file_name' of a Card identified by 'card_key'.
  
-[POSTPuts or updates the Form Data attachment with name "attachment-uploadto the specified Card.+[PUTUploads the Form Data attachment with name 'attachment-uploadto 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 request: +Example GET request: 
 <code> <code>
-https://example.protogrid.com/api/v2/apps/example/cards/89e74e40-b0ef-4bc3-8e89-a43a43763087/attachments/Bildschirmfoto%202021-01-22%20um%2014.11.15.png +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
-</code> +
- +
-Form Data:  +
-<code> +
-------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-- +
-</code> +
-Example response: +
-<code json> +
-+
-  "errors": [],  +
-  "result":+
-    "file_name": "Bildschirmfoto_2021-01-22_um_14.11.15.png" +
-  } +
-}+
 </code> </code>
  
-The code behind the attachment upload:+Example code for PUT request:
 <code javascript> <code javascript>
 var HOST = "https://example.protogrid.com/"; var HOST = "https://example.protogrid.com/";
-var APP_ID = "appc55b3773-5503-4c41-a9aa-3a561c40fa04"; +var APP_NAME = "example_app"; 
-var CARD_ID = "89e74e40-b0ef-4bc3-8e89-a43a43763087";+var CARD_KEY = "89e74e40-b0ef-4bc3-8e89-a43a43763087";
  
 function uploadFile(file, progressCallback, successCallback) { function uploadFile(file, progressCallback, successCallback) {
Line 304: Line 295:
     }     }
  
-    var attachment_base_url = HOST + "api/v2/apps/"APP_ID + "/cards/"CARD_ID + "/attachments/";+    var attachment_base_url = HOST + "api/v2/apps/"APP_NAME + "/cards/"CARD_KEY + "/attachments/";
     var initial_file_name = file.name;     var initial_file_name = file.name;
     var xhr = new XMLHttpRequest();     var xhr = new XMLHttpRequest();
-    xhr.open("POST", attachment_base_url + initial_file_name, true);+    xhr.open("PUT", attachment_base_url + initial_file_name, true);
     xhr.upload.addEventListener("progress", function(progress_event) {     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.         var progress = progress_event.loaded / progress_event.total * 66; // We want the progress bar to show "loading" until the server response is back.
Line 328: Line 319:
     });     });
     xhr.send(createFormData(file));     xhr.send(createFormData(file));
 +}
 +</code>
 +
 +
 +The corresponding Form Data: 
 +<code>
 +------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--
 +</code>
 +
 +Example response after successful attachment upload:
 +<code javascript>
 +{
 +  "errors": [], 
 +  "result": {
 +    "file_name": "Bildschirmfoto_2021-01-22_um_14.11.15.png"
 +  }
 } }
 </code> </code>
Line 335: Line 351:
    
 The following URL parameter can be used for paging: The following URL parameter can be used for paging:
-  * card_key: Passing a card_key will give you a result starting from that key 
   * limit: Defines how many proto keys are returned. Takes a number between 1 and 1000, default is 10.   * limit: Defines how many proto keys are returned. Takes a number between 1 and 1000, default is 10.
-The returned result contains a key "next_card_key" whose value is the next key not returned in this answer. Using the parameter "card_key" one can start the next page exactly at the next Proto.+The returned result contains a key "next_card_key" whose value is the next key not returned in this answer.
  
 Example request:  Example request: 
 <code> <code>
-https://example.protogrid.com/api/v2/apps/example/protos?card_key=ExampleProtoKey&limit=1+https://example.protogrid.com/api/v2/apps/example/protos?limit=1
 </code> </code>
  
 Example result:  Example result: 
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
   "protogrid_environment_version": "1.3.9",   "protogrid_environment_version": "1.3.9",
   "result": {   "result": {
-    next_card_key: "NextProtoKey" +    "next_card_key": "NextProtoKey" 
-    "protos":+    "protos":
-      {"key": "ExampleProtoKey", "shortname": {"en": "Proto: Example Proto"}}+      {"key": "ExampleProtoKey"}
     ]     ]
   }   }
Line 363: Line 378:
 Example request:  Example request: 
 <code> <code>
-https://example.protogrid.com/api/v2/apps/example/protos/example_proto+https://example.protogrid.com/api/v2/apps/example/protos/example_proto_key
 </code> </code>
  
 Example result: Example result:
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
   "protogrid_environment_version": "1.3.9",   "protogrid_environment_version": "1.3.9",
   "result": {   "result": {
-    "key": <proto_key>+    "key": "example_proto_key"
-    "shortname": example_proto,+    "shortname": "Example Proto",
     "field_and_widget_keys": [     "field_and_widget_keys": [
       {       {
Line 417: Line 432:
  
 The following URL parameter can be used for paging: The following URL parameter can be used for paging:
-  * card_key: Passing a card_key will give you a result starting from that key 
   * limit: Defines how many card keys are returned. Takes a number between 1 and 1000, default is 10.   * limit: Defines how many card keys are returned. Takes a number between 1 and 1000, default is 10.
  
-The returned result contains a key “next_card_key” whose value is the next key not returned in this answer. Using the parameter “card_key” one can start the next page exactly at the next Card.+The returned result contains a key “next_card_key” whose value is the next key not returned in this answer.
  
 Example request:  Example request: 
 <code> <code>
-https://example.protogrid.com/api/v2/apps/example/protos/example_proto/card-keys?card_key=ExampleCardKey&limit=1+https://example.protogrid.com/api/v2/apps/example/protos/example_proto/card-keys?limit=1
 </code> </code>
  
 Example result: Example result:
-<code json>+<code javascript>
 { {
   "errors": [],   "errors": [],
Line 434: Line 448:
   "result": [   "result": [
     "card_keys":[     "card_keys":[
 +      "ExampleProtoKey",
 +      "ExampleSortstring",
       "ExampleCardKey"       "ExampleCardKey"
     ],     ],
Line 442: Line 458:
  
 ==== /api/v2/apps/<app_name>/mailsend ==== ==== /api/v2/apps/<app_name>/mailsend ====
-[GET, POST] Send an email using the provided data+[POST] Send an email
  
-The following JSON data fields or URL parameters can be used: +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 yetplease contact [[protogrid-customer-support@ategra.ch|Protogrid Support]].
-  * to: TO address (multiple addresses separated by comma) +
-  * cc: CC address (multiple addresses separated by comma) +
-  * bcc: BCC address (multiple addresses separated by comma) +
-  * replyto: ReplyTo address +
-  * subject: Subject in plain text +
-  * body: Body text in plain text format (URL encoded) +
-  * bodyhtml: Body text in HTML format (URL encoded). If both body and bodyhtml are specififedonly bodyhtml will be used +
-  * attachments: weblink to attachment (URL encoded), multiple links separated by comma+
  
-Combinations of JSON data fields and URL parameters are allowed, whereas JSON data fields take precendence over URL parameters+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 profileand the fields "SMTP Server Hostname", "SMTP Server Port" and "SMTP Server Password").+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 function will fist try to establish a TLS session to the specified mail server and authenicate using the supplies 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 following JSON data fields can be used: 
 +  * to: TO addresses (Array of Strings, mandatory) 
 +  * cc: CC addresses (Array of Strings) 
 +  * bcc: BCC addresses (Array of Strings) 
 +  * reply_to: ReplyTo addresses (Array of Strings) 
 +  * from: From address if other than logged in user (String) 
 +  * subject: Subject (String, mandatory) 
 +  * body_text_plain: Body text in plain text format (String) 
 +  * body_text_html: Body text in HTML format (String) 
 +  * inline_images: Images for embedded display in HTML body using "cid" references (Array of Objects) 
 +  * attachments: Documents to attach to the email (Array of Objects)
  
-The returned result will contain the key success with value of true or a corresponding error message. +Attachments and inline images must already reside inside Protogrid, each attached to CardThe logged in user must have read access to this Card(s)Attachments and inline images are specified using an Object with the following structure
- +<code javascript>
-Example request:  +
-<code> +
-https://example.protogrid.com/api/v2/apps/example/mailsend?to=user1@example.com&cc=user2@example.com&subject=example&bcc=user@example.com&replyto=user@example.com&body=&bodyhtml=%3Chtml%3E%0A%3Cbody%3E%0A%0A%3Ch1%3EMy%20First%20Heading%3C%2Fh1%3E%0A%3Cp%3EMy%20first%20paragraph.%3C%2Fp%3E%0A%0A%3C%2Fbody%3E%0A%3C%2Fhtml%3E&attachments=https%3A%2F%2Fprotogrid.wiki%2Flib%2Ftpl%2Fpgrid-vector%2Fuser%2Flogo.png +
-</code> +
- +
-Example result+
-<code json>+
 { {
-   "errors" : [], +    "card_id": "<ID of the Card on which the attachment or image resides>", 
-   "protogrid_environment_version" : "2.1.3", +    "file_name": "<Name of the file as it is listed in the Card specified above>"
-   "result": {"success":true}+
 } }
 </code> </code>
  
 +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.
  
-Example client-side jQuery function to send mail: +The returned result will include a success message or details about the particular error.
-<code json>+
  
-$.get("https://example.protogrid.com/api/v2/apps/example/mailsend?to=user@example.com&subject=Test&body=This%20is%20a%20testmessage", function(data, status){ +Example client-side jQuery request
-    alert("Data: " + JSON.stringify(data)); +<code javascript>
-  }); +
-  +
 $.post({ $.post({
     url: "https://example.protogrid.com/api/v2/apps/example/mailsend",     url: "https://example.protogrid.com/api/v2/apps/example/mailsend",
     data: JSON.stringify({     data: JSON.stringify({
- "to": "user@example.com", +        "to": ["Tester 1️⃣ <test1@ategra.ch>", "Tester 2️⃣ <test2@ategra.ch>"]
- "cc": "user2@example.com", +        "cc": ["Tester 3️⃣ <test3@ategra.ch>", "Tester 4️⃣ <test4@ategra.ch>"]
- "subject": "Test", +        "bcc": ["Tester 5️⃣ <test5@ategra.ch>", "Tester 6️⃣ <test6@ategra.ch>"], 
- "body": "This%20is%20a%20testmessage", +        "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'     contentType: 'application/json; charset=utf-8'
 }).done(function (response) { }).done(function (response) {
-        alert("Data: " + JSON.stringify(response));+    alert("Data: " + JSON.stringify(response));
 }); });
 +</code>
  
 +As a response you receive a JSON with the following structure:
 +  * errors [Array]: Contains information if no single email could be sent, otherwise it is empty.
 +  * messages [Array]: Contains information if Protogrid could not establish the connection to the mail server with the most secure transport encryption, otherwise it is empty.
 +  * result [Object]: Contains information regarding individual recipients to whom the email could not be delivered. If the email could be delivered to all recipients equals to { "success": true }.
 +
 +Example response:
 +<code javascript>
 +{
 +    "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"
 +        ]
 +    }
 +}
 </code> </code>
Print/export