Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
protogrid:api_endpoints [2021-01-22 14:24] – [/api/v2/apps/<app_name>/cards/<card_key>/attachments/<attachment_key>] dru | protogrid:api_endpoints [2021-12-14 04:03] – [/api/v2/apps/<app_name>/mailsend] dru | ||
---|---|---|---|
Line 7: | Line 7: | ||
==== Example successful response ==== | ==== Example successful response ==== | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 20: | Line 20: | ||
==== Example failure response ==== | ==== Example failure response ==== | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 55: | Line 55: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 90: | Line 90: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 118: | Line 118: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 139: | Line 139: | ||
* end_key: [" | * end_key: [" | ||
* keys: [" | * keys: [" | ||
- | * page_number: | + | * page_number: |
- | * limit: Accepts a number, which defines how many cards are returned | + | * limit: Accepts a number, which defines how many Cards are returned |
* 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, | ||
+ | |||
| | ||
- | Note: you may only use either keys or start_key and end_key. | + | Please note: |
+ | * You may only use either | ||
+ | * 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:// | Details: For more details about the URL parameters see the [[http:// | ||
Line 169: | Line 173: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 176: | Line 180: | ||
" | " | ||
" | " | ||
- | {" | + | {" |
{…} | {…} | ||
] | ] | ||
Line 185: | Line 189: | ||
==== / | ==== / | ||
- | [POST] Creates a new card. It is necessary to specify a proto_key on which the card will be based. | + | [POST] Creates a new Card. It is necessary to specify a 'proto_key' denoting the Proto on which the new Card will be based. |
- | If a card key is specified, Protogrid | + | |
- | + | ||
- | Added functionality with | + | |
- | * 1.6.7: | + | |
- | * If you supply a list of cards, all of them will be created. | + | |
- | * The return value is now a list of all updated | + | |
Example request: | Example request: | ||
Line 198: | Line 196: | ||
</ | </ | ||
- | Together with the request, | + | In the POST request |
- | + | < | |
- | < | + | |
{ | { | ||
" | " | ||
- | " | + | " |
- | {" | + | { |
- | {…} | + | |
+ | | ||
+ | | ||
+ | … | ||
] | ] | ||
} | } | ||
Line 211: | Line 211: | ||
Example response: | Example response: | ||
- | + | < | |
- | < | + | |
{ | { | ||
" | " | ||
- | " | + | |
- | "results": { | + | |
+ | "result": { | ||
" | " | ||
" | " | ||
" | " | ||
+ | " | ||
… | … | ||
} | } | ||
Line 226: | Line 227: | ||
Deprecated functionalities: | Deprecated functionalities: | ||
- | * Specification of a user-defined | + | * Specification of a user-defined |
==== / | ==== / | ||
- | [GET] Returns a specific | + | [GET] Returns a specific |
- | [DELETE] | + | [DELETE] |
- | [POST] Updates | + | [POST] Updates |
Example request: | Example request: | ||
Line 240: | Line 241: | ||
</ | </ | ||
- | JSON: | + | 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: | + | |
- | {" | + | { |
- | " | + | |
- | | + | |
+ | | ||
+ | … | ||
] | ] | ||
} | } | ||
</ | </ | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
- | " | + | |
- | "results": { | + | |
+ | "result": { | ||
" | " | ||
" | " | ||
" | " | ||
+ | " | ||
… | … | ||
} | } | ||
Line 267: | Line 272: | ||
==== / | ==== / | ||
- | [GET] Shows the attachment identified by attachment_key. | + | [GET] Returns |
- | [POST] Puts or updates | + | [PUT] Uploads |
- | Example request: | + | Example |
< | < | ||
- | https:// | + | https:// |
- | </ | + | |
- | + | ||
- | Form Data: | + | |
- | < | + | |
- | ------WebKitFormBoundarya04hDppsnTo2uPOR | + | |
- | Content-Disposition: | + | |
- | + | ||
- | image/png | + | |
- | ------WebKitFormBoundarya04hDppsnTo2uPOR | + | |
- | Content-Disposition: | + | |
- | Content-Type: | + | |
- | + | ||
- | + | ||
- | ------WebKitFormBoundarya04hDppsnTo2uPOR-- | + | |
- | </ | + | |
- | Example response: | + | |
- | <code json> | + | |
- | { | + | |
- | " | + | |
- | " | + | |
- | " | + | |
- | } | + | |
- | } | + | |
</ | </ | ||
- | The code behind the attachment upload: | + | Example |
<code javascript> | <code javascript> | ||
var HOST = " | var HOST = " | ||
- | var APP_ID | + | var APP_NAME |
- | var CARD_ID | + | var CARD_KEY |
function uploadFile(file, | function uploadFile(file, | ||
Line 313: | Line 295: | ||
} | } | ||
- | var attachment_base_url = HOST + " | + | var attachment_base_url = HOST + " |
var initial_file_name = file.name; | var initial_file_name = file.name; | ||
var xhr = new XMLHttpRequest(); | var xhr = new XMLHttpRequest(); | ||
- | xhr.open(" | + | xhr.open(" |
xhr.upload.addEventListener(" | xhr.upload.addEventListener(" | ||
var progress = progress_event.loaded / progress_event.total * 66; // We want the progress bar to show " | var progress = progress_event.loaded / progress_event.total * 66; // We want the progress bar to show " | ||
Line 337: | Line 319: | ||
}); | }); | ||
xhr.send(createFormData(file)); | xhr.send(createFormData(file)); | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | |||
+ | The corresponding Form Data: | ||
+ | < | ||
+ | ------WebKitFormBoundarya04hDppsnTo2uPOR | ||
+ | Content-Disposition: | ||
+ | |||
+ | image/png | ||
+ | ------WebKitFormBoundarya04hDppsnTo2uPOR | ||
+ | Content-Disposition: | ||
+ | Content-Type: | ||
+ | |||
+ | |||
+ | ------WebKitFormBoundarya04hDppsnTo2uPOR-- | ||
+ | </ | ||
+ | |||
+ | Example response after successful attachment upload: | ||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
} | } | ||
</ | </ | ||
Line 344: | 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 " | + | The returned result contains a key " |
Example request: | Example request: | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example result: | Example result: | ||
- | < | + | < |
{ | { | ||
" | " | ||
" | " | ||
" | " | ||
- | next_card_key: | + | |
- | " | + | " |
- | {" | + | {" |
] | ] | ||
} | } | ||
Line 372: | Line 378: | ||
Example request: | Example request: | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example result: | Example result: | ||
- | < | + | < |
{ | { | ||
" | " | ||
" | " | ||
" | " | ||
- | " | + | " |
- | " | + | " |
" | " | ||
{ | { | ||
Line 426: | 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: | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example result: | Example result: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 451: | Line 456: | ||
==== / | ==== / | ||
- | [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 |
- | * 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 | + | |
- | * body: Body text in plain text format (URL encoded) | + | |
- | * bodyhtml: Body text in HTML format (URL encoded). If both body and bodyhtml are specififed, only bodyhtml will be used | + | |
- | * attachments: | + | |
- | Combinations of JSON data fields | + | Protogrid will fist try to establish a TLS session to the specified mail relay server |
- | The mail will be sent according to the currently logged in user (mail address specified in user profile, and the fields "SMTP Server Hostname", | + | The mail will be sent according to the currently logged in user (mail address specified in user profile and the field "SMTP Server Password" |
- | The function will fist try to establish a TLS session to the specified mail server and authenicate | + | 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_html: | ||
+ | * inline_images: | ||
+ | * attachments: | ||
- | The returned result will contain the key success with a value of true or a corresponding error message. | + | Attachments and inline images must already reside inside Protogrid, each attached to a Card. The logged in user must have read access |
- | + | < | |
- | Example request: | + | |
- | < | + | |
- | https:// | + | |
- | </ | + | |
- | + | ||
- | Example result: | + | |
- | < | + | |
{ | { | ||
- | "errors" : [], | + | |
- | "protogrid_environment_version" | + | "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 " | ||
- | 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(" | + | Example client-side jQuery request: |
- | | + | <code javascript> |
- | }); | + | |
- | | + | |
$.post({ | $.post({ | ||
url: " | url: " | ||
data: JSON.stringify({ | data: JSON.stringify({ | ||
- | " | + | |
- | " | + | " |
- | " | + | " |
- | "body": "This%20is%20a%20testmessage", | + | " |
- | }), | + | " |
+ | | ||
+ | "body_text_plain": " | ||
+ | " | ||
+ | " | ||
+ | {" | ||
+ | ], | ||
+ | " | ||
+ | {" | ||
+ | ] | ||
+ | | ||
contentType: | contentType: | ||
}).done(function (response) { | }).done(function (response) { | ||
- | | + | |
}); | }); | ||
+ | </ | ||
+ | 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 { " | ||
+ | |||
+ | Example response: | ||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | [ | ||
+ | " | ||
+ | " | ||
+ | ], | ||
+ | " | ||
+ | { | ||
+ | " | ||
+ | [ | ||
+ | 554, | ||
+ | "5.7.1 < | ||
+ | ] | ||
+ | } | ||
+ | } | ||
</ | </ |