Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
protogrid:api_endpoints [2021-02-11 22:08] – [/api/v2/apps/<app_name>/cards] 178.193.212.125 | protogrid:api_endpoints [2021-12-20 15:37] – [/api/v2/apps/<app_name>/protos/<proto_key>/card-keys] 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" | + | [POST] Creates a new Card. It is necessary to specify a 'proto_key' |
Example request: | Example request: | ||
Line 197: | Line 201: | ||
" | " | ||
" | " | ||
- | {" | + | { |
- | | + | |
+ | | ||
+ | | ||
+ | … | ||
] | ] | ||
} | } | ||
Line 207: | Line 214: | ||
{ | { | ||
" | " | ||
- | " | + | |
- | "results": { | + | |
+ | "result": { | ||
" | " | ||
" | " | ||
" | " | ||
+ | " | ||
… | … | ||
} | } | ||
Line 218: | Line 227: | ||
Deprecated functionalities: | Deprecated functionalities: | ||
- | * 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" | + | * 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' |
==== / | ==== / | ||
- | [GET] Returns a specific Card identified by "card_key". | + | [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. | + | [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 ' | + | [POST] Updates an existing Card identified by 'card_key'. If the ' |
Example request: | Example request: | ||
Line 235: | Line 244: | ||
<code javascript> | <code javascript> | ||
{ | { | ||
- | " | + | " |
- | " | + | " |
" | " | ||
- | {" | + | { |
- | | + | |
+ | | ||
+ | | ||
+ | … | ||
] | ] | ||
} | } | ||
Line 247: | Line 259: | ||
{ | { | ||
" | " | ||
- | " | + | |
- | "results": { | + | |
+ | "result": { | ||
" | " | ||
" | " | ||
" | " | ||
+ | " | ||
… | … | ||
} | } | ||
Line 258: | Line 272: | ||
==== / | ==== / | ||
- | [GET] Returns the attachment identified by attachment_key. | + | [GET] Returns the attachment identified by ' |
- | [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 304: | 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 328: | 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 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 " | + | The returned result contains a key " |
Example request: | Example request: | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example result: | Example result: | ||
- | < | + | < |
{ | { | ||
" | " | ||
" | " | ||
" | " | ||
- | next_card_key: | + | |
- | " | + | " |
- | {" | + | {" |
] | ] | ||
} | } | ||
Line 363: | Line 378: | ||
Example request: | Example request: | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example result: | Example result: | ||
- | < | + | < |
{ | { | ||
" | " | ||
" | " | ||
" | " | ||
- | " | + | " |
- | " | + | " |
" | " | ||
{ | { | ||
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: | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example result: | Example result: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 434: | Line 448: | ||
" | " | ||
" | " | ||
+ | " | ||
+ | " | ||
" | " | ||
], | ], | ||
Line 442: | Line 458: | ||
==== / | ==== / | ||
- | [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 < | ||
+ | ] | ||
+ | } | ||
+ | } | ||
</ | </ |