Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
| protogrid:api_endpoints [2017-12-08 11:44] – created 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 3: | Line 3: | ||
| 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. | 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. | ||
| - | === Response === | + | ===== Response |
| 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. | 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. | ||
| - | == Example successful response == | + | ==== Example successful response ==== |
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== Example failure response ==== | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | { … }, | ||
| + | { … } | ||
| + | ], | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ===== Field Types ===== | ||
| + | In Protogrid there exist different types of fields such as numbers, text or dates. | ||
| + | |||
| + | ==== Number Field ==== | ||
| + | ==== Text Field ==== | ||
| + | ==== Date Time Field ==== | ||
| + | Protogrid always uses [[https:// | ||
| + | ==== Relation Field ==== | ||
| + | ==== Role Field ==== | ||
| + | |||
| + | ==== Rich Text Field ==== | ||
| + | |||
| + | ===== Endpoints ===== | ||
| + | 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: | ||
| + | <code http> | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | Example response: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | … | ||
| + | }, | ||
| + | … | ||
| + | ] | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | [GET] Returns basic information about one Application. | ||
| + | |||
| + | Example request: | ||
| < | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | Example response: | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | [GET] Returns a list of all view names in this Application. | ||
| + | Details on what views are supported, see [[protogrid: | ||
| + | |||
| + | Example request: | ||
| + | |||
| + | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | Example response: | ||
| + | |||
| + | <code javascript> | ||
| { | { | ||
| - | " | + | |
| - | " | + | " |
| - | " | + | " |
| - | “key”: {…}, | + | " |
| - | “key”: […], | + | |
| - | “key”: “data” | + | {…} |
| - | } | + | ] |
| + | } | ||
| } | } | ||
| + | </ | ||
| + | ==== / | ||
| + | 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: | ||
| + | * start_key: [" | ||
| + | * end_key: [" | ||
| + | * keys: [" | ||
| + | * page_number: | ||
| + | * 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 | ||
| + | * Default value: 10 | ||
| + | * 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 | ||
| + | * Default value: False | ||
| + | * include_cards: | ||
| + | * Example: include_cards=true | ||
| + | * 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, | ||
| + | |||
| + | | ||
| + | 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:// | ||
| + | |||
| + | Full list of views can be found [[protogrid: | ||
| + | |||
| + | Example request: | ||
| + | |||
| + | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | 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: | ||
| + | |||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | {" | ||
| + | {…} | ||
| + | ] | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | |||
| + | [POST] Creates a new Card. It is necessary to specify a ' | ||
| + | |||
| + | Example request: | ||
| + | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | In the POST request body, a JSON object needs to be sent as shown in the following example: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | … | ||
| + | ] | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Example response: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | … | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | 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 ' | ||
| + | |||
| + | ==== / | ||
| + | [GET] Returns a specific Card identified by ' | ||
| + | |||
| + | [DELETE] Logically deletes a specific Card identified by ' | ||
| + | |||
| + | [POST] Updates an existing Card identified by ' | ||
| + | |||
| + | Example request: | ||
| + | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | In the POST request body, a JSON object needs to be sent as shown in the following example: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | }, | ||
| + | … | ||
| + | ] | ||
| + | } | ||
| + | </ | ||
| + | Example response: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | … | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | [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> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | [GET] Returns a list of all protos of the specified application. | ||
| + | |||
| + | The following URL parameter can be used for paging: | ||
| + | * limit: Defines how many proto keys are returned. Takes a number between 1 and 1000, default is 10. | ||
| + | The returned result contains a key " | ||
| + | |||
| + | Example request: | ||
| + | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | Example result: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | {" | ||
| + | ] | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | [GET] Returns detailed information about the specified Proto. | ||
| + | |||
| + | Example request: | ||
| + | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | Example result: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | … | ||
| + | ], | ||
| + | " | ||
| + | }, | ||
| + | {…}, | ||
| + | … | ||
| + | ] | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | [GET] Returns the keys for all Cards based on the specified proto. | ||
| + | |||
| + | The following URL parameter can be used for paging: | ||
| + | * 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. | ||
| + | |||
| + | Example request: | ||
| + | < | ||
| + | https:// | ||
| + | </ | ||
| + | |||
| + | Example result: | ||
| + | <code javascript> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | ], | ||
| + | " | ||
| + | ] | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | ==== / | ||
| + | [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 < | ||
| + | ] | ||
| + | } | ||
| + | } | ||
| </ | </ | ||
