2017.2

This release adds authentication to the API to prevent inappropriate access to data.

New methods: get_session_token and destroy_session_token. A call to get_session_token requires the user's qualified_assessor_id (user name) and password. The response contains a session_token field, which must be provided as a parameter for every other API method. Upon completion of a session, the destroy_session_token method can be triggered to invalidate the session token.

The session_token allows the API to permit and deny access to methods or results depending on the logged in user's permissions. Attempting to access methods or values that are not permitted results in a SOAP Fault response.

We have also taken this opportunity to clean up the API a bit by removing obsolete methods and fields.

Every method (except for get_session_token) now includes a mandatory session_token field. In addition, the following methods have been altered as documented:

  • archive_buildings_by_id, delete_buildings_by_id: 
    • qualified_assessor_id is removed. The user is determined from the session token.
    • The user must have the Assessor role and be the creator of the requested building (Note: This is not changed behavior but was hard-coded into the method previously and is now handled by the common access control layer).
  • calculate_base_building, calculate_package_building, commit_results
    • The fields validate_inputslog_type, and is_polling have been removed
    • Admin: All building IDs are permitted
    • Assessor: Only buildings assessed by the assessor are permitted
  • retrieve_extended_results, retrieve_inputs, retrieve_recommendations, retrieve_results, retrieve_label_results
    • The fields validate_inputslog_type, and is_polling have been removed
    • The values allowed to be in buildings or building_id are restricted based on the user's role(s)
      • Admin: All building IDs are permitted
      • Partner: Only buildings assessed by an assessor belonging to the Partner are permitted
      • Assessor: Only buildings assessed by the assessor are permitted
  • export_label_results
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Admin role to call this method
  • export_partner_label_results
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Partner role to call this method
  • generate_custom_label
    • The user must have the Admin role or must have the Assessor role and be the assessor that created both buildings
  • generate_label
    • is_polling is removed - this method already does not support asynchronous calls, so this has no impact on the method
    • The user must have the Admin role or must have the Assessor role and be the assessor that created the building
  • retrieve_buildings_by_id
    • If the user has the Admin role, no restrictions apply
    • Otherwise, if the user has the Assessor role, qualified_assessor_id must be set to the user's name
    • Users with only the Partner role may not use this method. They should use retrieve_buildings_by_partner instead
  • submit_address, submit_hpxml_inputs
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Assessor role
  • submit_inputs, validate_inputs
    • User must have the Assessor role and must be the user that created the building to be updated
  • retrieve_buildings_by_partner
    • partner is now optional
    • Admin: Must pass the partner field 
    • Partner: May not pass the partner field. Instead the method always returns results filtered for the currently logged-in partner.
  • These methods have been removed from the HEScore API
    • calculate_package_building_poll
    • calculate
    • doe2sim
    • doe2sim_multi
    • nearest_weather
    • retrieve_buildings_by_address (Use the address field of retrieve_buildings_by_id instead)
Subpages (25): View All
Comments