# REST - Data Objects

Data Objects (a.k.a. "Entities") are the manner by which Exago views and accesses the tables, views, procedures, etc., from the Data Sources. Data objects represent the structure of the data, but the actual data is only accessed at report run-time.

> Note. All requests require Session Id URL parameter and basic request headers. In the following examples, headers are omitted for clarity.

# Data Object JSON

Data Objects are represented as JSON objects with the following properties:

Name | Type | Writeable | Description
Id | string | required-create | The unique Id of this data object
Name | string | required | The display name ("alias") of this data object
Schema | string | yes | The schema of this data object
CategoryName | string | yes | The Category group of this data object
DataName | string | required | The name of this data object in its data source
DataSourceId | integer | required | The Id of the data source of this data object (see Data Sources)
DataType | enum | yes ("Table") | Data Object Type
SqlStatement | string | yes | The custom SQL of this data object if it is of type SqlStmt
Parameters | array of strings | yes | Any parameters for stored proc, assembly or web service calls.
KeyColumns | array of strings | yes | The unique key fields of this data object
TenantColumns | array of Tenant Column | yes | The tenant fields of this data object
FilterDropdownObject | Filter Dropdown | yes | The filter dropdown object of this data object

### Example

    {
      "Id":            "Employees_0",
      "Name":          "Employees",
      "Schema":        "dbo",
      "CategoryName":  "",
      "DataName":      "Employees",
      "DataSourceId":  "0",
      "DataType":      "Table",
      "SqlStatement":  "",
      "Parameters":    [],
      "KeyColumns":    ["EmployeeID"],
      "TenantColumns": [
        {
          "Column":    "EmployeeID",
          "Parameter": "UserId"
        }
      ],
      "FilterDropdownObject": {
        "FilterDbName":       "Employee_List",
        "FilterDataSourceId": -1,
        "FilterObjectType":   "view",
        "FilterSchema":       "",
        "FilterSqlStmt":      ""
      }
    }

# Tenant Column JSON

Tenant Columns are represented as JSON objects with the following properties:

Name | Type | Writeable | Description
Column | string | required | The tenant data field
Parameter | string | required | The tenant parameter

### Example

    "TenantColumns": [
        {
          "Column":    "EmployeeID",
          "Parameter": "UserId"
        }
      ]

# Filter Dropdown JSON

A Data Object's Filter Dropdown is represented as a JSON object with the following properties:

Name | Type | Writeable | Description
FilterDbName | string | required | The name of this data object in its data source
FilterObjectType | enum | yes | Data Object Type
FilterSchema | string | yes | The schema for this data object
FilterSqlStmt | string | yes | The custom SQL for this data object if it is of type SqlStmt

### Example

      "FilterDropdownObject": {
        "FilterDbName":       "Employee_List",
        "FilterObjectType":   "view",
        "FilterSchema":       "",
        "FilterSqlStmt":      ""
      }

# List Data Objects

    GET /rest/entities

List all the data objects in the current configuration. Output is an array of objects, each representing an individual data object.

Name | Type | Description
Id | string | The unique Id of this data object
Name | string | The display name ("alias") of this data object

### Using curl

    curl http://{webservice}/rest/entities?sid={sid} -X GET

### Example response

    Status: 200 OK

    [
      {
        "Id":   "Customers_0",
        "Name": "Customers"
      },
      {
        "Id":   "Employees_0",
        "Name": "Employees"
      },
      ...
    ]

# Show Data Object

    GET /rest/entities/{Id}

Show the properties of the data object specified by its Id.

### Using curl

    curl http://{webservice}/rest/entities/{Id}?sid={sid} -X GET

### Example response

    Status: 200 OK

    {
      "Id":            "Employees_0",
      "Name":          "Employees",
      "Schema":        "dbo",
      "CategoryName":  "",
      "DataName":      "Employees",
      "DataSourceId":  "0",
      "DataType":      "Table",
      ...
    }

# Create Data Object

    POST /rest/entities

Requires a DataName or a custom SqlStatement. One or more KeyColumns are required for most data types.

### Using curl

    curl http://{webservice}/rest/entities?sid={sid} -X POST ^
    	-d @newDataObject.txt

newDataObject.txt

    "{'Id':'Employees_1','Name':'Employees','Schema':'dbo','DataName':'Employees','DataSourceId':0,'KeyColumns':['EmployeeID']}"

### Example response

    Status: 201 Created
    Location: /{webservice}/rest/Entities/Employees_1

    {
      "Id":            "Employees_1",
      "Name":          "Employees",
      "Schema":        "dbo",
      "CategoryName":  "",
      "DataName":      "Employees",
      "DataSourceId":  "0",
      "DataType":      "Table",
      "SqlStatement":  "",
      "Parameters":    [],
      "KeyColumns":    ["EmployeeID"],
      "TenantColumns": [],
      "FilterDropdownObject": null
    }

# Edit Data Object

    PATCH /rest/entities/{Id}

Only supply the properties to be edited.

### Using curl

    curl http://{webservice}/rest/entities/{Id}?sid={sid} -X PATCH ^
    	-d "{'Name':'Staff List'}"

### Example response

    Status: 204 No Content

# Delete Data Object

    DELETE /rest/entities/{Id}

### Using curl

    curl http://{webservice}/rest/entities/{Id}?sid={sid} -X DELETE

### Example response

    Status: 204 No Content

# Data Field JSON

Data fields for each object are represented as JSON objects with the following properties. The actual data in the fields is not accessible via REST. Data fields cannot be created or deleted. However, some metadata for existing fields can be edited.

Name | Type | Writeable | Description
Id | string | no | The unique name for this data field
Name | string | yes | The display name for this data field
Type | enum | yes | Data Field Type
IsFilterable | bool (pre-v2017.2) | yes | Whether this field is filterable
const (v2017.2+) | Filterable Type
IsVisible | boolean | yes | Whether this field is visible

# List Data Fields of a Data Object

    GET /rest/entities/{Id}/fields

List all the data fields in the data object specified by its Id. Output is an array of objects, each representing an individual data field.

Name | Type | Description
Id | string | The unique Id of this data field
Name | string | The display name of this data field

### Using curl

    curl http://{webservice}/rest/entities/{Id}/fields?sid={sid} -X GET

### Example response

    Status: 200 OK

    [
      {
        "Id":   "Address",
        "Name": "Address"
      },
      {
        "Id":   "BirthDate",
        "Name": "Date of Birth"
      },
      {
        "Id":   "EmployeeID",
        "Name": "ID Number"
      },
      {
        "Id":   "FirstName",
        "Name": "First Name"
      },
      {
        "Id":   "LastName",
        "Name": "Last Name"
      },
      ...
    ]

# Show Data Field

    GET /rest/entities/{Id}/fields/{Field Id}

Show the properties of the data field specified by its Id, of the data object specified by its Id.

### Using curl

    curl http://{webservice}/rest/entities/{Id}/fields/{Field Id}?sid={sid} -X GET

### Example response

    Status: 200 OK

    {
      "Id":           "LastName",
      "Name":         "Last Name",
      "Type":         "String",
      "IsFilterable": true,
      "IsVisible":    true
    }

# Edit Data Field

    PATCH /rest/entities/{Id}/fields/{Field Id}

Only supply the properties to be edited.

### Using curl

    curl http://{webservice}/rest/entities/{Id}/fields/{Field Id]?sid={sid} -X PATCH ^
    	-d "{'Name':'Surname'}"

### Example response

    Status: 204 No Content