Database API documentation version v10

http://server:port/activeviam/database/rest/v10

Home

This document describes the REST API of Database.

Note: the root URL provided here will depend of the deployment of your application.

/branches

API to create, update permissions and delete branches. This can only be used to manage the branches and not the data on the branches.

post

post

Create a new branch by doing an empty commit on a new branch without any data change. The new branch is a fork identical to the parent branch. The permissions can also be set on creation.

Create a new branch by doing an empty commit on a new branch without any data change. The new branch is a fork identical to the parent branch. The permissions can also be set on creation.

Body

Type: application/json

Schema:

{
	"$schema": "http://json-schema.org/draft-03/schema",
	"type": "object/",
	"properties": {
		"branch": {
			"description": "The name of the new branch.",
			"type": "string",
			"required": true
		},
		"parent": {
			"description": "The name of the parent branch. The new branch will be a fork of the parent. Default is master.",
			"type": "string",
			"required": false
		},
		"expectedEpoch": {
			"description": "The expected epoch for the new branch. The creation fails if the parent branch is not at this epoch.",
			"type": "integer",
			"required": false
		},
		"permissions": {
			"description": "The branch permissions.",
			"type": "object",
			"properties": {
				"owners": {
					"type": "array",
					"items":	{
						"type": "string"
					},
					"required": true
				},
				"readers": {
					"type": "array",
					"items":	{
						"type": "string"
					},
					"required": true
				}
			 },
			"required": false
		}
	}
}

Example:

{
	"name" : "test-new-branch",
	"parent" : "parent-branch",
	"permissions" : {
		"owners" : [ "admin" ],
		"readers" : [ "admin", "USER_ROLE" ]
	}
}

HTTP status code 200

Body

Type: application/json

Example:

{
	"permissions" : {
		"owners" : [ "admin" ],
		"readers" : [ "admin", "USER_ROLE" ]
	}
}

put delete

put

Update the security of a branch. Permissions can be a user name, a role or the constant string __ALL_USERS__ for all users. Requires to be owner of the branch.

delete

Delete a branch. Requires to be owner of the branch.

Update the security of a branch. Permissions can be a user name, a role or the constant string __ALL_USERS__ for all users. Requires to be owner of the branch.

Path Parameters

  • branchName: required (string)

Body

Type: application/json

Schema:

{
	"$schema": "http://json-schema.org/draft-03/schema",
	"type": "object",
	"properties": {
		"description" : "owners and readers of the branch. Elements can be user names, roles or the constant __ALL_USERS__ to give access to all users",
		"owners": {
			"type": "array",
			"items": {
				"type": "string"
			},
			"required": true
		},
		"readers": {
			"type": "array",
			"items": {
				"type": "string"
			},
			"required": true
		}
	}
}

Example:

{
	"owners" : [ "admin", "ROLE_ADMIN" ],
	"readers" : [ "__ALL_USERS__" ]
}

HTTP status code 200

Body

Type: application/json

Example:

{
	"permissions" : {
		"owners" : [ "admin", "ROLE_ADMIN" ],
		"readers" : [ "__ALL_USERS__" ]
	}
}

Delete a branch. Requires to be owner of the branch.

Path Parameters

  • branchName: required (string)

HTTP status code 200

Body

Type: application/json

Example:

{
	"ok"
}

post

post

Fast-forward a branch to another one. The fast-forwarded branch is moved to the target head. It can only be done if the target has been forked from the branch and no new commit happened on the branch since. This requires owner permissions on the branch that is fast-forwarded and read permissions on the target.

Fast-forward a branch to another one. The fast-forwarded branch is moved to the target head. It can only be done if the target has been forked from the branch and no new commit happened on the branch since. This requires owner permissions on the branch that is fast-forwarded and read permissions on the target.

Path Parameters

  • branchName: required (string)

Query Parameters

  • fastForward: required (string)

    The name of the target branch where this branch will be fast fowarded.

HTTP status code 200

Body

Type: application/json

Example:

{
	"ok"
}

/data

API to retrieve or update data.

get post

API to access query features of the database.

get

Retrieve rows from the selected table, with the given query parameters. This does not support conditions, use the POST API for that.

post

Retrieve rows from the selected table, with the given parameters in json format

Retrieve rows from the selected table, with the given query parameters. This does not support conditions, use the POST API for that.

Path Parameters

  • tableName: required (string)

Query Parameters

  • branch: (string)

    The branch on which to retrieve rows. Default is master branch.

  • epoch: (number)

    The epoch on which to retrieve rows. Default is latest.

  • pageSize: (integer)

    The maximum number of rows in the page. Default is 100.

  • page: (integer)

    The page to return. First page (and default) is 1.

  • fields: (string)

    The fields (columns) of the rows to retrieve, separated by commas. If not specified, all the fields are returned.

HTTP status code 200

Body

Type: application/json

Example:

{
	"epoch" : 185,
	"headers" : [
		{
			"name": "Id",
			"type": "long"
		},
		{
			"name": "ProductId",
			"type": "int"
		},
		{
			"name": "Desk",
			"type": "String"
		}
	],
	"rows" : [
		[ 100001, 128, "DeskA" ],
		[ 100002, 64, "DeskB" ],
		[ 100001, 128, "DeskA" ]
	],
	"pagination" : {
		"previousPage" : 1,
		"currentPage" : 2,
		"nextPage" : 3,
		"previousPageUrl" : "/data/tables/myTable?pageSize=20&page=1",
		"nextPageUrl" : "/data/tables/myTable?pageSize=20&page=3"
	}
}

Retrieve rows from the selected table, with the given parameters in json format

Path Parameters

  • tableName: required (string)

Query Parameters

  • pageSize: (integer)

    The maximum number of rows in the page. Default is 100.

  • page: (integer)

    The page to return. First page (and default) is 1.

  • query: (string)

    Deprecated.

Body

Type: application/json

Schema:

{
	"$schema": "http://json-schema.org/draft-03/schema",
	"type": "object/",
	"properties": {
		"conditions": {
			"description": "Conditions to filter the rows that should be returned",
			"type": "object",
			"required": false
		},
		"fields": {
			"description": "List of the fields (columns) of the rows that should be returned. If null all the field are returned",
			"type": "array",
			"items": {
				"type": "string"
			},
			"required": "false"
		},
		"epoch": {
			"description": "Optional category for the message",
			"type": "string",
			"dependencies": {
				"branch": [ "master" ]
			}
		},
		"branch": {
			"description": "The name of the branch to retrieve rows from",
			"type": "string",
			"required": false
		},
		"timeout": {
			"description": "Delay in milliseconds to wait at most for the query to complete. 0 means no timeout. Default it defined by the configuration of the database rest service, or 30 seconds if not specified",
			"type": "integer",
			"required": false,
			"minimum": 0
		},
		"distinct": {
			"description": "Flag to switch between a distinct query on the field. If set to true, the distinct tuples of the selected fields are returned. If set to false, all the tuples are returned.",
			"type": "boolean",
			"required": false
		}
	}
}

Example:

Basic example
{
	"conditions" : {"year" : 2010, "currency" : "EUR"},
	"fields" : [ "CounterParty", "Rating", "City" ],
	"epoch" : 185,
	"branch" : "master",
	"timeout" : 30000
}

Following examples show the possibilities in conditions 
Comparator ($eg, $lt, $lte, $gt, $gte)
{
	"conditions" : { 
		"year" : {"$lt" : 2018 }
	}
}

$in operator for lists
{
	"conditions" :  { 
		"year" : {
			"$in" : [ 2010, 2011] 
		}
	}
}


$or, $and, $not
{
	"conditions" : { 
		"currency" : "EUR", 
		"$or": [ 
			{"year" : 2010},
			{"id" : {"$lt" : 15000 }}
		]
}

$like on strings
{
	"conditions" :  { 
		"currency" : {
			"$like" : "U" }
		}
}

HTTP status code 200

Body

Type: application/json

Example:

{
	"epoch" : 185,
	"headers" : [
		{
			"name": "Id",
			"type": "long"
		},
		{
			"name": "ProductId",
			"type": "int"
		},
		{
			"name": "Desk",
			"type": "String"
		}
	],
	"rows" : [
		[ 100001, 128, "DeskA" ],
		[ 100002, 64, "DeskB" ],
		[ 100001, 128, "DeskA" ]
	],
	"pagination" : {
		"previousPage" : 1,
		"currentPage" : 2,
		"nextPage" : 3,
		"previousPageUrl" : "/data/tables/myTable?pageSize=20&page=1",
		"nextPageUrl" : "/data/tables/myTable?pageSize=20&page=3"
	}
}

post

API update the content of the database (add, update, remove).

post

Update a table on a specific branch. This requires to be owner of the branch and the permission to update the fields or insert/delete in the table.

Update a table on a specific branch. This requires to be owner of the branch and the permission to update the fields or insert/delete in the table.

Path Parameters

  • branchName: required (string)

Body

Type: application/json

Schema:

{
	"$schema": "http://json-schema.org/draft-03/schema",
	"type": "object/",
	"properties": {
		"actions": {
			"description": "The list of actions to execute.",
			"type" : "array",
			"items": {
				"type": "object",
				"properties": {
					"action" : {
						"enum": ["INSERT", "DELETE", "UPDATE"],
						"description" : "The action type.",
						"required" : "true"
					},
					"baseTable" : {
						"type" : "string",
						"required" : "true"
					},
					"lines" : {
						"type" : "array",
						"description" : "the lines to insert, only used by INSERT action",
						"items" : {
							"type" : "array",
							"items" : {
								"type" : "object"
							}
						},
						"required" : "false"
					},
					"where" : {
						"description" : "the condition for UPDATE and DELETE",
						"type" : "object",
						"required" : "false"
					},
					"updateProcedure" : {
						"description" : "the update procedure (only used by UPDATE)",
						"type" : "object",
						"required" : "false"
					}
				}
			},
			"required": true
		},
		"expectedEpoch": {
			"description": "The expected epoch for the new branch",
			"type": "integer",
			"required": false
		},
		"context": {
			"description": "The context values containing the statistics option.",
			"type": "object",
			"properties": {
				"statisticsOption": {
					"enum": [ "NONE", "ESTIMATION", "EXACT"],
					"description": "the statistics option for the queries"
				}
			},
			"required": "false"
		}
	}
}

Example:

{
	"actions" :  [
		{
			"action" : "INSERT",
			"baseTable" : "Trade",
			"lines" : [
				[ 1, "EUR", 128 ],
				[ 2, "USD", 256 ]
			]
		},
		{
			"action" : "UPDATE",
			"baseTable" : "CounterParty",
			"where" : {
				"City" : "London"
			},
			"updateProcedure" : {
				"Rating" : "AA"
			}
		},
		{
			"action" : "DELETE",
			"baseTable" : "CounterParty",
			"where" : {
				"City" : "Paris"
			},
		}
	],
	"expectedEpoch" : 200,
	"context" : {
		"statisticsOption" : "ESTIMATION"
	}
}

HTTP status code 200

Body

Type: application/json

Example:

{
	"Trade" : {
		"insertedRows" : 2
	},
	"CounterParty" : {
		"updatedRows" : 20,
		"deletedRows" : 30
	}
}

/discovery

API to access discovery features of the database

get

get

Get the full description of the database : tables, joins and branches

Get the full description of the database : tables, joins and branches

HTTP status code 200

Body

Type: application/json

Example:

{
	"joins": {
		"CounterParty": {
			"CounterpartyToCity": {
				"targetTable": "City",
				"fieldMappings": {
					"City": "Name"
				}
			}
		},
		"Risk": {
			"RiskToTrade": {
				"targetTable": "Trade",
				"fieldMappings": {
					"TradeId": "Id"
				}
			}
		}
	},
	"tables": {
		"CounterParty": {
			"fields": [
				{
					"name": "CounterParty",
					"index": 0,
					"type": "String",
					"defaultValue": 0,
					"readOnly": false,
					"hasParser": true
				},
				{
					"name": "Rating",
					"index": 3,
					"type": "String",
					"defaultValue": "N/A",
					"readOnly": false,
					"hasParser": true
				},
				{
					"name": "City",
					"index": 4,
					"type": "String",
					"defaultValue": 0,
					"readOnly": false,
					"hasParser": true
				}
			],
			"keyFields": [
				0
			],
			"canInsert": true,
			"canEdit": true,
			"canDelete": true
		},
		"Forex": {
			"fields": [
				{
					"name": "Currency",
					"index": 0,
					"type": "String",
					"defaultValue": 0,
					"readOnly": false,
					"hasParser": true
				},
				{
					"name": "TargetCurrency",
					"index": 1,
					"type": "String",
					"defaultValue": 0,
					"readOnly": false,
					"hasParser": true
				},
				{
					"name": "Rate",
					"index": 2,
					"type": "double",
					"defaultValue": 0,
					"readOnly": false,
					"hasParser": true
				}
			],
			"keyFields": [
				0,
				1
			],
			"canInsert": true,
			"canEdit": true,
			"canDelete": true
		},
	},
	"branches": {
		"master": {
			"owners": [
				"ROLE_ADMIN"
			],
			"readers": [
				"ROLE_USER",
				"ROLE_ADMIN"
			],
			"latestepoch": "75"
		}
	},
	"separator": "/"
}

get

get

Get the table names that exist in the database

get

get

Get the description of all the tables in the database visible to the current user.

get

get

Get the description of the given table name

Get the description of the given table name

Path Parameters

  • tableName: required (string)

HTTP status code 200

Body

Type: application/json

Example:

{
	"fields": [
		{
			"name": "CounterParty",
			"index": 0,
			"type": "String",
			"defaultValue": 0,
			"readOnly": false,
			"hasParser": true
		},
		{
			"name": "CounterPartyGroup",
			"index": 1,
			"type": "String",
			"defaultValue": 0,
			"readOnly": false,
			"hasParser": true
		},
		{
			"name": "Sector",
			"index": 2,
			"type": "String",
			"defaultValue": "N/A",
			"readOnly": false,
			"hasParser": true
		},
		{
			"name": "Rating",
			"index": 3,
			"type": "String",
			"defaultValue": "N/A",
			"readOnly": false,
			"hasParser": true
		},
		{
			"name": "City",
			"index": 4,
			"type": "String",
			"defaultValue": 0,
			"readOnly": false,
			"hasParser": true
		}
	],
	"keyFields": [
		0
	],
	"canInsert": true,
	"canEdit": true,
	"canDelete": true
}

get

API to access size of the database.

get

Retrieve size of the selected table.

Retrieve size of the selected table.

Path Parameters

  • tableName: required (string)

HTTP status code 200

Body

Type: text/plain

Example:

42

get

get

Get the description of all the visible joins in the database

get

get

Get the joins of the provided owner table name

Get the joins of the provided owner table name

Path Parameters

  • ownerTable: required (string)

HTTP status code 200

Body

Type: application/json

Example:

{
	"TradeToCounterparty": {
		"targetTable": "CounterParty",
		"fieldMappings": {
			"CounterParty": "CounterParty"
		}
	},
	"TradeToProduct": {
		"targetTable": "Product",
		"fieldMappings": {
			"ProductId": "Id"
		}
	}
}

get

get

Get the description of all the branches. Only shows branches where the current user has read permissions.

get

get

Get the description of a specific branch

Get the description of a specific branch

Path Parameters

  • branchName: required (string)

HTTP status code 200

Body

Type: application/json

Example:

{
	"owners": [
		"ROLE_USER"
	],
	"readers": [
		"ROLE_USER"
	],
	"latestepoch": "80"
}

get

get

Get the separator used to concatenate the elements of a field path into a String