Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
protogrid:api_endpoints [2018-10-10 10:19] – 46.140.51.3 | protogrid:api_endpoints [2021-12-20 15:38] (current) – [/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 37: | Line 37: | ||
==== Text Field ==== | ==== Text Field ==== | ||
==== Date Time Field ==== | ==== Date Time Field ==== | ||
- | Protogrid always uses ISO 8601 standard in UTC timezone for storing date time values. | + | Protogrid always uses [[https:// |
==== Relation Field ==== | ==== Relation Field ==== | ||
==== Role Field ==== | ==== Role Field ==== | ||
+ | ==== Rich Text Field ==== | ||
- | ===== End Points | + | ===== Endpoints |
The Protogrid JSON API offers the following API endpoints: | The Protogrid JSON API offers the following API endpoints: | ||
Line 54: | Line 55: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 89: | Line 90: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 117: | Line 118: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 138: | 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 148: | 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 168: | Line 173: | ||
Example response: | Example response: | ||
- | < | + | < |
{ | { | ||
" | " | ||
Line 175: | Line 180: | ||
" | " | ||
" | " | ||
- | {" | + | {" |
{…} | {…} | ||
] | ] | ||
Line 184: | 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 197: | Line 196: | ||
</ | </ | ||
- | Together with the request, | + | In the POST request |
- | + | < | |
- | < | + | |
{ | { | ||
" | " | ||
- | " | + | " |
- | {" | + | { |
- | {…} | + | |
+ | | ||
+ | | ||
+ | … | ||
] | ] | ||
} | } | ||
Line 210: | Line 211: | ||
Example response: | Example response: | ||
- | + | < | |
- | < | + | |
{ | { | ||
" | " | ||
- | " | + | |
- | "results": { | + | |
+ | "result": { | ||
" | " | ||
" | " | ||
" | " | ||
+ | " | ||
… | … | ||
} | } | ||
Line 225: | 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 239: | 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": { | ||
" | " | ||
" | " | ||
" | " | ||
+ | " | ||
… | … | ||
+ | } | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ==== / | ||
+ | [GET] Returns the attachment identified by ' | ||
+ | |||
+ | [PUT] Uploads the Form Data attachment with name ' | ||
+ | |||
+ | Example GET request: | ||
+ | < | ||
+ | https:// | ||
+ | </ | ||
+ | |||
+ | Example code for PUT request: | ||
+ | <code javascript> | ||
+ | var HOST = " | ||
+ | var APP_NAME = " | ||
+ | var CARD_KEY = " | ||
+ | |||
+ | function uploadFile(file, | ||
+ | function createFormData(file) { | ||
+ | var data = new FormData(); | ||
+ | data.append(" | ||
+ | data.append(" | ||
+ | return data; | ||
+ | } | ||
+ | |||
+ | var attachment_base_url = HOST + " | ||
+ | var initial_file_name = file.name; | ||
+ | var xhr = new XMLHttpRequest(); | ||
+ | xhr.open(" | ||
+ | xhr.upload.addEventListener(" | ||
+ | var progress = progress_event.loaded / progress_event.total * 66; // We want the progress bar to show " | ||
+ | progressCallback(progress); | ||
+ | }); | ||
+ | xhr.addEventListener(" | ||
+ | if (xhr.status == 200) { | ||
+ | var saved_filename = initial_file_name; | ||
+ | if (xhr.response && typeof(xhr.response) === ' | ||
+ | var response = JSON.parse(xhr.response); | ||
+ | if (response && typeof(response) === ' | ||
+ | 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: | ||
+ | |||
+ | image/png | ||
+ | ------WebKitFormBoundarya04hDppsnTo2uPOR | ||
+ | Content-Disposition: | ||
+ | Content-Type: | ||
+ | |||
+ | |||
+ | ------WebKitFormBoundarya04hDppsnTo2uPOR-- | ||
+ | </ | ||
+ | |||
+ | Example response after successful attachment upload: | ||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
} | } | ||
} | } | ||
Line 269: | 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 297: | Line 378: | ||
Example request: | Example request: | ||
< | < | ||
- | https:// | + | https:// |
</ | </ | ||
Example result: | Example result: | ||
- | < | + | < |
{ | { | ||
" | " | ||
" | " | ||
" | " | ||
- | " | + | " |
- | " | + | " |
" | " | ||
{ | { | ||
Line 351: | 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 368: | Line 448: | ||
" | " | ||
" | " | ||
+ | " | ||
+ | " | ||
" | " | ||
], | ], | ||
" | " | ||
] | ] | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ==== / | ||
+ | [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-customer-support@ategra.ch|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" | ||
+ | |||
+ | 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: | ||
+ | |||
+ | 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: | ||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | 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 " | ||
+ | |||
+ | The returned result will include a success message or details about the particular error. | ||
+ | |||
+ | Example client-side jQuery request: | ||
+ | <code javascript> | ||
+ | $.post({ | ||
+ | url: " | ||
+ | data: JSON.stringify({ | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | {" | ||
+ | ], | ||
+ | " | ||
+ | {" | ||
+ | ] | ||
+ | }), | ||
+ | contentType: | ||
+ | }).done(function (response) { | ||
+ | alert(" | ||
+ | }); | ||
+ | </ | ||
+ | |||
+ | 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 < | ||
+ | ] | ||
+ | } | ||
} | } | ||
</ | </ |