# Starting a REST Session

Sessions are the means by which REST persists changes through multiple API calls. A REST session allows for you to easily encapsulate a group of user-specific changes. Most REST changes will only affect the current session. (Folder changes are the exception.) However, once an API session is committed and Exago is launched, a user will be able to make such changes as their role permits.

> Note. All requests require basic request headers. In the following examples, headers are omitted for clarity.

# Entering the API

A POST /Sessions call should always be the first made when entering the API. This creates a session, which contains a Session Id and an AppUrl.

### Session Id

The Session Id is a GUID which uniquely identifies the instance of Exago you're working in. Example:

    3c04c155-3317-4dab-a2ee-09572e3a8e44

This Id is passed as a URL parameter to all other method calls.

### AppUrl

The AppUrl is a string which encodes the session information in a format readable by the host application. Example:

    ExagoHome.aspx?d=fk7hInneiNI7yUR1n8fCjjbTuIdTWgQrj8AaUlzO8l7K5JMaf7DhbZxzaSAXthP3bWLA%2fzG4AtXApO6pGoBpzQ%3d%3d&showerrordetail=true

The AppUrl consists of three components: the Home Page, an alphanumeric string, and the ShowErrorDetail URL parameter. Retrieving the AppUrl via GET /Sessions/{Id} should always be the last call made when finishing in the API.

Once you have committed your API changes and want to launch Exago, append the AppUrl to the end of your Exago base URL and launch the full URL string in a browser:

    http://yoursite.com/exago/ExagoHome.aspx?d=fk7hInneiNI7yUR1n8fCjjbTuIdTWgQrj8AaUlzO8l7K5JMaf7DhbZxzaSAXthP3bWLA%2fzG4AtXApO6pGoBpzQ%3d%3d&showerrordetail=true

An AppUrl can only be used once. Launching an API session will permanently close it, and apply your custom variables into a new user session in the host application.

# Session JSON

The Sessions endpoint allows for creation and deletion of sessions and access to some general settings. It also allows you to specify and configure the action that the session will take when launched. To launch a report in the full user interface, it needs to be set in Sessions as the output report.

Sessions are represented as JSON objects with the following properties:

Name | Type | Writeable | Description
Id | string | no | The unique Id of this session ("sid")
AppUrl | string | no | The AppUrl of this session. Changes to reflect any modifications made to this session in the API.
Page | string | yes ("ExagoHome") | The Exago home page
ApiAction | enum | yes ("Default") | Api Action, to take when this session is launched
ExportType | enum | yes | Export Type, if ApiAction is 'ExecuteReport'
ShowTabs | boolean | yes (true) | Whether the tab bar should be shown
ShowErrorDetail | boolean | yes (true) | Whether detailed error messages should be shown
ReportSettings | Report | yes | A report with optional sorts & filters if ApiAction is 'ExecuteReport' or 'EditReport'

### Example

    {
      "AppUrl": "ExagoHome.aspx?d={alphanumeric}&showerrordetail=true",
      "Id":              "{sid}"
      "Page":            "ExagoHome",
      "ApiAction":       "ExecuteReport",
      "ExportType":      "Html",
      "ShowTabs":        true,
      "ShowErrorDetail": true,
      ...
    }

## Report JSON

If you want to edit or launch a report, specify a report in the ReportSettings property. Reports are represented as JSON objects with the following properties:

Name | Type | Writeable | Description
Id | string | no | The unique Id of the this report
ReportPath | string | yes | Full path from root folder to this report
SortsResource | Sorts | yes | Any sorts to apply to this report
FilterItems | array of Filter | yes | Any filters to apply to this report
IsError | boolean | no | Whether there were any validation errors when loading this report
ErrorList | array of const | no | If IsError = true, a list of errors encountered when loading this report. Possible Errors

### Example

    "ReportSettings": {
      "Id": "ad0f442e-275b-48a0-893f-0b1255ee7880",
      "ReportPath": "Reports\\Product Sales Report",
      "SortsResource": null,
      "FilterItems": [],
      "IsError": false,
      "ErrorList": null
    }

> Note. Windows file paths are delineated by double-backslashes: \\

## Sorts

Sorts can be added to the report, either in addition to, or replacing its existing sorts. This only affects the current session, and does not edit the base report. The collection of sorts to be added is represented as a JSON object with the following properties:

Name | Type | Writeable | Description
ReplaceFlag | string | yes (false) | Whether to replace all existing report sorts
SortItems | array of Sort | yes | List of sorts to apply to this report

### Example

    {
      "ReplaceFlag": false,
      "SortItems": [
        {
          "Id":  "Products.ProductName",
          "Asc": false
        },
        {
          "Id":  "Categories.CategoryName",
          "Asc": false
        }
        ...
      ]
    }

## Sort

Each sort in the SortItems property is represented as a JSON object with the following properties:

Name | Type | Writeable | Description
Id | string | required | Data field to sort on. Format: "EntityName.ColumnName"
Asc | boolean | yes (false) | Whether sort direction is ascending

### Example

    {
      "Id":  "Products.ProductName",
      "Asc": false
    }

## Filter

Filters can be added to the report in addition to its existing filters. This only affects the current session, and does not edit the base report. Each filter to be added is represented as a JSON object with the following properties:

Name | Type | Writeable | Description
Name | string | required | Data field to filter on. Format: "EntityName.ColumnName"
EntityName | string | yes | Entity name to filter on (deprecated)
ColumnName | string | yes | Column name to filter on (deprecated)
DataType | enum | yes ("string") | Data Field Type
Operator | enum | yes ("EqualTo") | Filter Operator Type
Values | array of strings | yes | Values to filter with
AndFlag | boolean | yes (true) | Whether this filter should be AND-ed with the next (versus OR-ed)
Prompt | boolean | yes (false) | Whether this filter should prompt the user for a value (Advanced or Express Reports)
GroupWithNext | boolean | yes (false) | Whether this filter should be grouped with the next (Advanced or Express Reports)

### Example

    {
      "Name": "Categories.CategoryName",
      "DataType": "string",
      "Operator": "OneOf",
      "Values": [
        "Beverages", "Seafood", "Produce"
      ],
      "AndFlag": true,
      "Prompt": false,
      "GroupWithNext": false
    }

# Create a Session

    POST /rest/sessions

### Available parameters

Name | Type | Description
config | string | Specify which config file to create the session with. Format: `CustomConfigFile` Caution. All config files must use the same Temp path. Otherwise, you may experience errors when loading sessions.

### Using curl

    curl http://{webservice}/rest/sessions -X POST ^
    	-d "{'Page':'Reporting','ApiAction':'Home','ShowTabs':false}"

### Example response

    Status: 201 Created
    Location: /{webservice}/rest/Sessions/{sid}

    {
      "AppUrl": "Reporting.aspx?d={alphanumeric}",
      "Id":              "{sid}",
      "Page":            "Reporting",
      "ApiAction":       "Home",
      "ExportType":      null,
      "ShowTabs":        false,
      "ShowErrorDetail": true,
      "ReportSettings": {
        "ReportPath": null,
        "SortsResource": null,
        "FilterItems": null
      }
    }

# Show a Session

    GET /rest/sessions/{sid}

If the session is launched, the session object is deleted and can no longer be viewed.

> Note. Unlike other resources, the {sid} is passed as part of the endpoint string, not as a URL parameter.

### Using curl

    curl http://{webservice}/rest/sessions/{sid} -X GET

### Example response

    Status: 200 OK

    {
      "AppUrl": "Reporting.aspx?d={alphanumeric}",
      "Id":   "{sid}",
      "Page": "Reporting",
      ...
    }

# Edit a Session

    PATCH /rest/sessions/{sid}

Only supply the properties to be edited. If the session is launched, the session object is deleted and it can no longer be edited.

> Note. Unlike other resources, the {sid} is passed as part of the endpoint string, not as a URL parameter.

### Using curl

    curl http://{webservice}/rest/sessions/{sid} -X PATCH ^
    	-d "{'Page':'CompanyHome'}"

### Example response

    Status: 200 OK

    {
      "AppUrl": "Reporting.aspx?d={alphanumeric}",
      "Id":   "{sid}",
      "Page": "CompanyHome",
      ...
    }

# Delete a Session

    DELETE /rest/sessions/{sid}

If a session is deleted, the AppUrl can no longer be used. If the session is launched, the session object is deleted and it can no longer be edited.

> Note. Unlike other resources, the {sid} is passed as part of the endpoint string, not as a URL parameter.

### Using curl

    curl http://{webservice}/rest/sessions/{sid} -X DELETE

### Example response

    Status: 204 No Content

# Launch a Report with Sorts and Filters

    POST /rest/sessions

Set the ApiAction to 'ExecuteReport', and specify a report, with any optional sorts and filters, in the ReportSettings property. If you want to save the report to a file, set the ExportType to the desired file type.

### Using curl

    curl http://{webservice}/rest/sessions -X POST ^
    	-d @sessionSettings.txt

sessionSettings.txt

    "{'ApiAction':'ExecuteReport','ExportType':'html','ReportSettings':{'ReportPath':'Sales\\Products','FilterItems':[{'Name':'Categories.CategoryID','DataType':'Integer','Values':["123"]}],'SortsResource':{'ReplaceFlag':true,'SortItems':[{'Id':'Categories.CategoryID','Asc':true}]}}}"

### Response

    Status: 201 Created
    Location: /{webservice}/rest/Sessions/{sid}

    {
      ...
      "ApiAction":       "ExecuteReport",
      "ExportType":      "Html",
      ...
      "ReportSettings": {
        ...
        "ReportPath": "Sales\\Products",
        "SortsResource": {
          "ReplaceFlag": true,
          "SortItems": [
            {
              "Id": "Categories.CategoryID",
              "Asc": true
            }
          ]
        },
        "FilterItems": [
          {
            "Name": "Categories.CategoryID",
            "DataType": "Integer",
            "Values": ["123"]
          }
        ]
      }
    }

To launch the report in Exago, take the AppUrl, and append it to the URL to your Exago installation to create the full URI path:

http://{website}/{exago}/{AppUrl}

### Example

    http://yoursite.com/reporting/homepage?d={alphanumeric}&showerrordetail=true