REST APIs

The solutions framework provides standard APIs via REST. The base URI for these REST APIs is:

Example:

The following services are provided:

• /solutions
• /solutions/attributevalue
• /solutions/attributevalue/{class}
• /solutions/attributevalue/{class}/{name}{query}
• GET /solutions/data
• PUT /solutions/data
• GET /solutions/hierarchies
• GET /solutions/hierarchies/{dimension}
• GET /solutions/hierarchies/{dimension}/{root}
• PUT /solutions/hierarchies/{dimension}/{root}{query}

To execute any solutions framework REST API, you must first create a session. For more information, see Creating a New Session - POST "/API/session" .

Remember to delete any session created after you are finished with it. For more information, see Destroying a Session – DELETE “/API/session” .

Responses

The following response headers will be returned with every request:

The following standard response statuses may be returned in the response header for a request:

/solutions

This endpoint will return a list of links to the solutions API services provided in JSON format.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ authorization.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

URI Example:

Return Type: application/json

/solutions/attributevalue

This endpoint will return a list of links to the solutions attribute value services provided in JSON format.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ authorization.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

URI Example:

Return Type: application/json

/solutions/attributevalue/{class}

This endpoint will return a list of links to specific attributes, of the class specified, available to query provided in JSON format.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ authorization.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

Request parameters:

class (string): the attribute class (symbol, system, or user).

URI Example:

Return Type: application/json

Possible Responses

/solutions/attributevalue/{class}/{name}{query}

This endpoint will return the value of the attribute, provided in text/plain format.

If you return the result to an object in application framework the attribute value will be stored in the _data property of the target object.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ authorization.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

Request parameters:

class (string): the attribute class (symbol, system, or user).

name (string): the name of the attribute.

query (string, optional): contains the query parameters for the attribute value request. Query parameters are required for symbol and user attribute value requests and take the form:

?object={objectName}

where:

• objectName is the name of a symbol when {class} is symbol.
• objectName is the name of a user when {class} is user.

URI Example:

Return Type: text/plain

CAD

Possible Responses

GET /solutions/data

This endpoint allows you to retrieve data. The formats supported are text/csv and application/json.

GET /solutions/data{query}

Use this endpoint with a GET request to retrieve data using an ad hoc query specification.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ and ‘View Data’ authorizations.

Request headers:

• LongviewWebSID (string): Specifies the Longview session identifier that grants access to the API.

• Accept (string): Specifies the acceptable response format and must be either text/csv or application/json.

• LVJSONFormat (string): Specifies the JSON format to use when Accept is application/json and must be either CONCISE or VERBOSE. If not specified data will be returned in the CONCISE format.

Request parameters:

query (string): contains the query parameters for the data request. Query parameters are required to specify the data to retrieve and take the form:

{dimension}={symbol}

where:

• dimension is the name of a dimension in the system.

• symbol is the name of a symbol in the specified dimension.

A query parameter must be provided for each dimension in the system.

Additional query parameters may be provided as follows:

• dataOption: specifies the scope of data to retrieve, and must be one of these values:

  • STANDARDALL (default) – retrieves all parent and leaf data in the area specified.

  • STANDARDLEADONLY – retrieves leaf data in the area specified.

  • LEAFDATA – retrieve all leaf data in the area specified, excluding any calculated data.

• unadjusted (string): specifies the type of data to retrieve and must be one of these values:

  • false (default) – retrieve adjusted data.

  • true – retrieve unadjusted data.

• schedule: specifies the name of a schedule from which to retrieve data.

• JSONFormat: specifies the JSON format to return when the Accept header is application/json. This query parameter supersedes the LVJSONFormat request header and must be one of these values:

  • CONCISE (default) – retrieve data as JSON in a concise format.

  • VERBOSE – retrieve data as JSON in a verbose format.

URI Example:

Return Type: text/csv

Return Type: application/json (VERBOSE)

The returned data includes an array of objects with one object for each data point returned:

Return Type: application/json (CONCISE)

The returned data includes an object with one metadata property describing the data and an array of data records, with each record being an array of values:

Restrictions

The following restrictions apply to this request:

• Each dimension parameter specifies a single symbol name.
• Hierarchical specifications are not supported, and all queries are executed as #99.
• When a schedule is specified all symbols in each dimension of the schedule are included in the query

GET /solutions/data/{name}{query}

Use this endpoint with a GET request to retrieve data using a pre-defined query specification.

The request requires you to provide the name of the API configuration file that contains the data spec definition and export spec definition that define how the data will be exported.

Available templates:

• Data GET – Single Value
• Data GET – Multiple Values

For more information on the Data GET templates, see the Creating data get APIs in the Longview Designer guide.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ and ‘View Data’ authorizations.

Request headers:

    LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

    Accept (string): specifies the acceptable response format and must be either text/csv or application/json.

    LVJSONFormat (string): specifies the JSON format to use when Accept is application/json and must be either CONCISE or VERBOSE. If not specified data will be returned in the CONCISE format.

Request parameters:

• name (string): is the name of the API configuration file created using an API Data GET templates.

  For more information on the Data GET templates, see the Creating data get APIs in the Longview Designer Guide.

• query (string, optional): contains the query parameters for the data request. Query parameters are required to specify any variables contained in the API configuration and take the form:

  {variableName}={value}

  where:

  • variableName is the name of a variable defined in the API configuration.

  • value is the value to use for the variable.

Additional query parameters may be provided as follows:

• JSONFormat: specifies the JSON format to return when the Accept header is application/json. This query parameter supersedes the LVJSONFormat request header and must be one of these values:

  • CONCISE (default) – retrieve data as JSON in a concise format.

  • VERBOSE – retrieve data as JSON in a verbose format.

URI Example

Pre-defined query has a variable named TIMEPERIODS defined.

Return Type: text/csv

The retuned data includes a header row followed by a row for each data point returned:

Return Type: application/json (VERBOSE)

The returned data includes an array of objects with one object for each data point returned:

Where the property names are the field names, as defined in the pre-defined query.

Return Type: application/json (CONCISE)

The returned data includes an object with one metadata property describing the data and an array of data records, with each record being an array of values:

Where the metadata consists of the field names, as defined in the pre-defined query, and the data includes the related symbol name for each dimension and the corresponding value.

Possible Responses

Additional Response Headers

Additional response headers are included in the response.

PUT solutions/data

This endpoint allows you to update data. The formats supported are text/csv and application/json.

PUT /solutions/data{query}

Use this endpoint with a PUT request to update data using an ad hoc query specification.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ and ‘Modify Data’ authorizations.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

Content-Type (string): specifies the format of the data provided with the request and must be either text/csv or application/json.

Request parameters:

• query (string): contains the query parameters for the data request. Query parameters are required to specify the data to retrieve and take the form:

  {dimension}={symbol}

  where:

  • dimension is the name of a dimension in the system.

  • symbol is the name of a symbol in the specified dimension.

  A query parameter must be provided for each dimension in the system.

  Additional query parameters may be provided as follows:

• schedule: used to update data for a specific schedule.

• headerRecords: to indicate the number of header records in the content to be ignored. Applies only when Content-Type is text/csv.

• footerRecords: to indicate the number of footer records in the content to be ignored. Applies only when Content-Type is text/csv.

URI Example

Content-Type: text/csv

Content-Type: application/json (VERBOSE)

The content must include an array of objects with one object for each data point returned:

Where each object includes these properties:

• Each dimension name in lower case, with the related symbol name as the value.

• A property named value, with the corresponding value.

Content-Type: application/json (CONCISE)

The content must include an object with one metadata property describing the data and an array of data records, with each record being an array of values:

Where the metadata consists of each dimension name in lower case and value and the data includes the related symbol name for each dimension and the corresponding value.

Content-Type: application/json (oData)

Where each object includes these properties:

• Each dimension name in lower case, with the related symbol name as the value.

• A property named value, with the corresponding value.

Restrictions

The following restrictions apply to this request:

• Each dimension parameter specifies a single symbol name.
• Hierarchical specifications are not supported, and all queries are executed as #99.
• Import is always done FULL and not INCREMENTAL.
• When a schedule is not specified, BASE data is submitted.
• If a schedule is specified, it must be the last field in the body before the data value.
• Max Errors is set to 0.

PUT /solutions/data/{name}{query}

Use this endpoint with a PUT request to update data using a pre-defined specification.

Available templates:

• Data PUT – Single Value
• Data PUT – Multiple Values

For more information on the Data PUT templates, see the Creating data put APIs in the Longview Designer guide.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ and ‘Modify Data’ authorizations.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

Content-Type (string): specifies the format of the data provided with the request and must be either text/csv or application/json.

Request parameters:

query (string, optional): contains the query parameters for the data request. Query parameters are required to specify any variables contained in the API configuration and take the form:

where:

• variableName is the name of a variable defined in the API configuration.
• value is the value to use for the variable.

URI Example

Content-Type: text/csv

Content-Type: application/json (VERBOSE)

The returned data includes an array of objects with one object for each data point returned:

Where the property names are the field names, as defined in the pre-defined specification, and the data includes the related symbol name for each dimension and the corresponding value.

Content-Type: application/json (CONCISE)

The returned data includes an object with one metadata property describing the data and an array of data records, with each record being an array of values:

Where the metadata consists of the field names, as defined in the pre-defined query, and the data includes the related symbol name for each dimension and the corresponding value.

Where the property names are the field names, as defined in the pre-defined specification, and the data includes the related symbol name for each dimension and the corresponding value.

Possible Responses

Additional Response Headers

Additional response headers are included in the response.

GET /solutions/hierarchies

This endpoint will return a list of links to the hierarchies API services provided in JSON format.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ authorization.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

URI Example:

Return Type: application/json

Possible Responses

GET /solutions/hierarchies/{dimension}

This endpoint will return a list of links to the hierarchies API services for the specified dimension provided in JSON format.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ authorization.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

Request parameters:

dimension (string): the name of the dimension.

URI Example:

Return Type: application/json

Possible Responses

GET /solutions/hierarchies/{dimension}/{root}

This endpoint will return the hierarchy of the specified root symbol in plain text, in the same format as the ExportHierarchy command in Application Framework.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’ authorization.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

Request parameters:

dimension (string): the name of the dimension.

root (string): the name of the root symbol in the dimension.

URI Example:

Return Type: text/plain

Possible Responses

PUT /solutions/hierarchies/{dimension}/{root}{query}

Use this endpoint with a PUT request to update a specific symbol hierarchy.

Authorizations Required:

To execute this API the user must have the ‘Connect to Application Framework’, ‘Symbols Create’, ‘Symbols Delete’, and ‘Symbols Modify’ authorizations.

Request headers:

LongviewWebSID (string): specifies the Longview session identifier that grants access to the API.

Request parameters:

• dimension (string): the name of the dimension.

• root (string): the name of the root symbol in the dimension.

• query (string, optional): contains the query parameters for the hierarchy request. Query parameters are required to specify any variables contained in the API configuration and take the form:

  The following query parameters are supported:

  • Execute: specifies the execution mode of the PUT request and must be one of these values:

    • SIMULATE (default) – Generates a plain text output file for each type of command that would be executed if the Execute query parameter value was specified as True.

    • True - Implements the instructions and commits the designated changes to the destination hierarchy.

  • Delete: indicates what action should be taken with any symbols existing in the target symbol hierarchy which are not specified in the request body.

    • (default) The symbols are not actually deleted; they are re-assigned to the {dimension}_DELETED hierarchy structure.

    • True – Signifies that the symbol will be completely removed from the database.

URI Example:

Content-Type: text/plain

Possible Responses