This is an old revision of the document!


JSON API Endpoints

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

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

{
  "errors": [], 
  "protogrid_environment_version": "1.3.9",
  "result":{
    "key": {…},
    "key": […],
    "key": "data"
  }
}

Example failure response

{
  "errors": [
    { … },
    { … }
  ], 
  "protogrid_environment_version": "1.3.9",
  "result": {}
}

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 ISO 8601 standard in UTC timezone for storing date time values.

Relation Field

Role Field

Rich Text Field

Endpoints

The Protogrid JSON API offers the following API endpoints:

/api/v2/apps

[GET] Returns a list of all Applications to which the authenticated user has access to.

Example request:

https://example.protogrid.com/api/v2/apps

Example response:

{
  "errors": [], 
  "protogrid_environment_version": "1.3.9",
  "result":[
    {
      "app_id": "app_example_id", 
      "description": "Example App", 
      "logo_url": "", 
      "theme_color": "blue-dark", 
      "title": "Example App ", 
      "url": "/example", 
      "url_name": "example"
    },
    {
      "app_id": "appID",
      "description": "Your awesome app",
      …
    },
    …
  ]
}

/api/v2/apps/<app_name>

[GET] Returns basic information about one Application.

Example request:

https://example.protogrid.com/api/v2/apps/example

Example response:

{ 
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "result": { 
    "app_id": "appID",
    "description": "Example App",
    "logo_url": "",
    "theme_color": "blue-dark",
    "title": "Example App ", 
    "url": "/example",
    "url_name": "example"
  }
}

/api/v2/apps/<app_name>/views

[GET] Returns a list of all view names in this Application. Details on what views are supported, see all available views.

Example request:

https://example.protogrid.com/api/v2/apps/example/views

Example response:

{
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "result": {
    "views": [
      {"view_name": "examples_by_id"},
      {…}
    ]
  }
}

/api/v2/apps/<app_name>/views/<view_name>

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: [“proto_key”, “column_key”, “filter_value”, null], 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
  • page_number: Set to 1 if on the first page, otherwise 2
  • limit: Accepts a number, which defines how many cards are returned in the result object.
    • Example: limit=15
    • Default value: 10
  • descending: If set to true the results will be in descending order.
    • Example: descending=true
    • Default value: False
  • include_cards: If set to true the result contains the cards for the keys as well.
    • Example: include_cards=true
    • Default value: False

Note: you may only use either keys or start_key and end_key.

Details: For more details about the URL parameters see the CouchDB documentation.

Full list of views can be found here.

Example request:

https://example.protogrid.com/api/v2/apps/example/views/example_view?start_key=["example_proto_key",null]&end_key=["example_proto_key",{}]&page_number=1&limit=2&descending=false

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:

{
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "result": {
    "next_card_key": "key",
    "rows": [
      {"key": "example_document_key", "shortname": "example_shortname"},
      {…}
    ]
  }
}

/api/v2/apps/<app_name>/cards

[POST] Creates a new Card. It is necessary to specify a “proto_key” denoting the Proto on which the new Card will be based. Initial values for the “design_elements” can 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.

Example request:

https://example.protogrid.com/api/v2/apps/example/cards

In the POST request body, a JSON object needs to be sent as shown in the following example:

{ 
  "proto_key": "some_proto_key",
  "design_elements": [
    {"definition_key": "example_design_element_key", "value":"example_value"},
    {}
  ]
}

Example response:

{
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "results": {
    "_id": "some_card_id",
    "_rev": "some_rev_id",
    "denormalized": {},}
}

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” property. 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.

/api/v2/apps/<app_name>/cards/<card_key>

[GET] Returns a specific Card identified by card_key.

[DELETE] Deletes a specific Card identified by card_key logically. The 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.

[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.

Example request:

https://example.protogrid.com/api/v2/apps/example/cards/some_card_id

In the body of the POST request, you need to send a JSON object as shown in the following example:

{
  "_id": some_card_id,
  "proto_key": some_proto_key,
  "design_elements": [
    {"definition_key": "example_design_element_key", "value": "example_value"},
    {}
  ]
}

Example response:

{
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "results": {
    "_id": "some_card_id",
    "_rev": "some_rev_id",
    "denormalized": {},}
}

/api/v2/apps/<app_name>/cards/<card_key>/attachments/<file_name>

[GET] Returns the attachment identified by attachment_key.

[POST] Puts or updates the Form Data attachment with name “attachment-upload” to the specified Card.

Example request:

https://example.protogrid.com/api/v2/apps/example/cards/89e74e40-b0ef-4bc3-8e89-a43a43763087/attachments/Bildschirmfoto%202021-01-22%20um%2014.11.15.png

Form Data:

------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--

Example response:

{
  "errors": [], 
  "result": {
    "file_name": "Bildschirmfoto_2021-01-22_um_14.11.15.png"
  }
}

The code behind the attachment upload:

var HOST = "https://example.protogrid.com/";
var APP_ID = "appc55b3773-5503-4c41-a9aa-3a561c40fa04";
var CARD_ID = "89e74e40-b0ef-4bc3-8e89-a43a43763087";
 
function uploadFile(file, progressCallback, successCallback) {
    function createFormData(file) {
        var data = new FormData();
        data.append("Content-Type", file.type);
        data.append("attachment-upload", file);
        return data;
    }
 
    var attachment_base_url = HOST + "api/v2/apps/" + APP_ID + "/cards/" + CARD_ID + "/attachments/";
    var initial_file_name = file.name;
    var xhr = new XMLHttpRequest();
    xhr.open("POST", attachment_base_url + initial_file_name, true);
    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.
        progressCallback(progress);
    });
    xhr.addEventListener("load", function() {
        if (xhr.status == 200) {
            var saved_filename = initial_file_name;
            if (xhr.response && typeof(xhr.response) === 'string' && xhr.response !== '') {
                var response = JSON.parse(xhr.response);
                if (response && typeof(response) === 'object' && response.result && typeof(response.result) === 'object' && response.result.file_name && typeof(response.result.file_name) === 'string' && response.result.file_name !== '') {
                    saved_filename = response.result.file_name;
                }
            }
            progressCallback(100);
            successCallback({
                url: attachment_base_url + saved_filename
            });
        }
    });
    xhr.send(createFormData(file));
}

/api/v2/apps/<app_name>/protos

[GET] Returns a list of all protos of the specified application.

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.

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.

Example request:

https://example.protogrid.com/api/v2/apps/example/protos?card_key=ExampleProtoKey&limit=1

Example result:

{
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "result": {
    next_card_key: "NextProtoKey"
    "protos":[
      {"key": "ExampleProtoKey", "shortname": {"en": "Proto: Example Proto"}}
    ]
  }
}

/api/v2/apps/<app_name>/protos/<proto_key>

[GET] Returns detailed information about the specified Proto.

Example request:

https://example.protogrid.com/api/v2/apps/example/protos/example_proto

Example result:

{
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "result": {
    "key": <proto_key>,
    "shortname": example_proto,
    "field_and_widget_keys": [
      {
        "allow_new_cards": true,
        "cardinality_setting": 2,
        "couchdb_viewname": "",
        "disable_label": false,
        "display_priority": 7,
        "element_type": "Relation",
        "grid_size_setting": 0,
        "help_text": "",
        "hidden": false,
        "label_multilanguage_key": "&&mlkey_design_elements",
        "multiple_values_setting": 1,
        "name": "card_design_elements",
        "parent_application_setting": "",
        "parent_entity_proto_setting": "DesignElementDefinition",
        "requirement_setting": 0,
        "show_card_type": true,
        "show_created_setting": false,
        "show_creator_setting": false,
        "show_modified_setting": false,
        "show_modifier_setting": false,
        "show_short_name_setting": false,
        "show_to_users": 0,
        "user_enabled_setting": 0,
        "value": [
          "design_element_key_1 ",
          "design_element_key_2",
          …
        ],
        "value_type": "key"
      },
      {…},
      …
    ]
  }
}

/api/v2/apps/<app_name>/protos/<proto_key>/card-keys

[GET] Returns the keys for all Cards based on the specified proto.

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.

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.

Example request:

https://example.protogrid.com/api/v2/apps/example/protos/example_proto/card-keys?card_key=ExampleCardKey&limit=1

Example result:

{
  "errors": [],
  "protogrid_environment_version": "1.3.9",
  "result": [
    "card_keys":[
      "ExampleCardKey"
    ],
    "next_card_key": "NextCardKey"
  ]
}

/api/v2/apps/<app_name>/mailsend

[GET, POST] Send an email using the provided data

The following JSON data fields or URL parameters can be used:

  • 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 specififed, only 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

The mail will be sent according to the currently logged in user (mail address specified in user profile, and the fields “SMTP Server Hostname”, “SMTP Server Port” and “SMTP Server Password”).

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 returned result will contain the key success with a value of true or a corresponding error message.

Example request:

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

Example result:

{
   "errors" : [],
   "protogrid_environment_version" : "2.1.3",
   "result": {"success":true}
}

Example client-side jQuery function to send mail:

$.get("https://example.protogrid.com/api/v2/apps/example/mailsend?to=user@example.com&subject=Test&body=This%20is%20a%20testmessage", function(data, status){
    alert("Data: " + JSON.stringify(data));
  });
 
$.post({
    url: "https://example.protogrid.com/api/v2/apps/example/mailsend",
    data: JSON.stringify({
		"to": "user@example.com",
		"cc": "user2@example.com",
		"subject": "Test",
		"body": "This%20is%20a%20testmessage",
		}),
    contentType: 'application/json; charset=utf-8'
}).done(function (response) {
        alert("Data: " + JSON.stringify(response));
});
Print/export