get-data-points

Specification Version

Version: "1"

Context and rules

Required for the StructuredData capability.

Called when a visualisation is loaded, to get the data which is displayed in the visualisation.

Which data is returned may depend upon the options the user has chosen for the underlying dataset. These options are passed in as input to this endpoint under DataExtract.Options. The structure of these options is determined by the schema returned from the endpoint endpoint-prefix-aireframe-get-dataset-options-schema.

Endpoint specification

• Name: endpoint-prefix-aireframe-get-data-points
• Verb: POST
• Authentication: Client credentials

Input

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "get-data-points-input",
	"type": "object",
	"properties": {
		"SubjectIdentifiers": {
			"type": "array",
			"items": {
				"type": "string"
			}
		},
		"PagingRequest": {
			"type": "object",
			"properties": {
				"After": {
					"type": ["string", "null"],
					"description": "Request items after the node with provided cursor"
				},
            	"Before": {
					"type": ["string", "null"],
          			"description": "Request items before the node with provided cursor"
				},
            	"First": {
					"type": ["integer", "null"],
          			"description": "Request the first x items",
					"format": "int32"
				},
            	"Last": {
					"type": ["integer", "null"],
          			"description": "Request the last x items.",
					"format": "int32"
				},
            	"OrderBy": {
					"type": ["string", "null"],
          			"description": "Gets the key of the field to order by."
				},
				"OrderDirection": {
					"description": "Gets the direction to order by.",
					"oneOf": [
						{
							"type": "null"
						},
						{
							"type": "string",
							"enum":	["Ascending", "Descending"]
						}
					]
				}
			},
			"required": [
				"After",
				"Before",
				"First",
				"Last",
				"OrderBy",
				"OrderDirection"
			]
		},
		"DataExtract": {
			"type": "object",
			"properties": {
			    "Key":{
			        "type": "string"
			    },
			    "Options": {
			        "type": "object"	    		
			    }
			},
			"required": [
				"Key",
				"Options"
			]
		}
	},
	"required": [
		"SubjectIdentifiers",
		"PagingRequest",
		"DataExtract"
	]
}

• Example:

{
	"SubjectIdentifiers": [
		"subj-123",
		"subj-456"
	],
	"PagingRequest": {
		"After": null,
		"Before": null,
		"First": 10,
		"Last": null,
		"OrderBy": null,
		"OrderDirection": "Ascending"
	},
	"DataExtract": {
		"Key": "sales-data-extract",
		"Options": {
			"info-type": "sales"
		}
	}
}

• Explanation of properties: Any object can be passed in to the DataExtract Options property that meets the schema returned by the endpoint endpoint-prefix-aireframe-get-dataset-options-schema. You may then use these options to determine what data to return.

Response

• Format: JSON
• Schema:

{
	"$schema": "http://json-schema.org/draft-04/schema#",
	"title": "get-data-points-response",
	"type": "object",
	"properties": {
		"PageInfo": {
			"type": "object",
			"properties": {
				"HasNextPage": {
					"type": "boolean"
				},
				"HasPreviousPage": {
					"type": "boolean"
				},
				"StartCursor": {
					"type": ["null", "string"]
				},
				"EndCursor": {
					"type": ["null", "string"],
					"minLength": 1
				},
				"TotalCount": {
					"type": "integer",
					"format": "int32"
				}
			},
			"required": [
				"HasNextPage",
				"HasPreviousPage",
				"TotalCount"
			]
		},
		"Edges": {
			"type": "array",
			"items": {
				"required": [
					"Node",
					"Cursor"					
				],
				"properties": {
					"Node": {
						"type": "object",
      					"description": "A collection of DataPointItems relating to a single point (e.g. time) for a single subject",
						"properties": {
							"Id": {
								"type": "string"
							},
							"SubjectIdentifier": {
								"type": "string",
          						"description": "The SubjectIdentifier that this Node refers to"
							},
							"DataPointItems": {
								"type": "array",
								"items": {
									"description": "A single data value",
									"required": [
										"Key",
										"Value"
									],
									"properties": {
										"Key": {
											"type": "string"
										},
										"Value": {
											"type": "object",
											"properties": {
												"DataType": {
													"type": "string",
													"enum": [
														"String",
														"Decimal",
														"Integer",
														"DateTime",
														"Date",
														"Time",
														"Boolean"
													]
												},
												"Value": {
													"type": [
														"string",
														"integer",
														"number",
														"boolean",
														"null"
													]
												}
											},
											"required": [
												"DataType"
											]
										}
									}
								}
							}
						},
						"required": [
							"Id",
							"SubjectIdentifier",
							"DataPointItems"
						]
					},
					"Cursor": {
						"type": "string",
          				"description": "Gets a unique identifier for this node."
					}
				}
			}
		}
	},
	"required": [
		"PageInfo",
		"Edges"
	]
}

• Additional Notes Depending on the DataType of a Value, the Value should be returned as the following C# type

  • String - null or string
  • Decimal - null or double
  • Integer - null or int
  • DateTime - null or string as DateTime format O
  • Date - null or string as DateOnly format yyyy-MM-dd
  • Time - null or string as TimeOnly format HH:mm:ss
  • Boolean - null or bool

• Example

{
	"PageInfo": {
		"HasNextPage": false,
		"HasPreviousPage": false,
		"StartCursor": "1",
		"EndCursor": "1",
		"TotalCount": 1
	},
	"Edges": [
		{
			"Node": {
				"Id": "1",
				"SubjectIdentifier": "subj-123",
				"DataPointItems": [
					{
						"Key": "STATUS",
						"Value": {
							"DataType": "String",
							"Value": "Ready"
						}
					},
					{
						"Key": "START_OF_PERIOD",
						"Value": {
							"DataType": "Date",
							"Value": "2023-09-25"
						}
					},
					{
						"Key": "END_OF_PERIOD",
						"Value": {
							"DataType": "Date",
							"Value": "2024-06-08"
						}
					},
					{
						"Key": "NUMBER_OF_RUNS",
						"Value": {
							"DataType": "Integer",
							"Value": 1
						}
					}
				]
			},
			"Cursor": "1"
		}
	]
}

Previous versions

None