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”: {}
}

End Points

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.

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 described above 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 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"},
			{…}
		]
	}
}
Print/export