1. Pearl API Versioning

The following are the steps for creating a new version for the Pearl API. The new version created in these steps is v1.1.0

Go to pearlcertification.public_api.versions.ApiVersion and add new class attribute for the new version V1p1p0="v1.1.0"
Create the python package of the new version v1p1p0
Copy the same urls.py module that was under the previous version and paste it under the new version
In the new urls.py file:
- Change the app_name from v1p0p0 to v1p1p0
- Change "pearlcertification.public_api.v1p0p0.urls" to "pearlcertification.public_api.v1p1p0.urls"
- Update the 2 instances of ApiVersion.V1p0p0 to ApiVersion.V1p1p0 (new version)
Add a new url for the new version under pearlcertification/public_api/urls.py
Start making the necessary changes under the new version package:
- A change in a method in the viewset requires creating a new viewset, subclassing the old then make the change and finally update the urls to point to the new viewset
- A change in the serializer requires creating a new serializer that is a subclass of the old one, creating a new viewset that is a subclass of the old viewset, updating the serializer class of the viewset to point to the new serializer and updating the corresponding url to point to the new viewset.
- A change in the data mapper requires creating a new data mapper that is a subclass of the old one, creating a new viewset that is a subclass of the old viewset, updating the data mapper class of the viewset to point to the new data mapper and updating the corresponding url to point to the new viewset.
Tests for the changes need to be added under pearlcertification/public_api/tests/<new_version>/
For the pearlcertification.public_api.client.PublicApiClient
- Update the api_version argument of __init__ to the new version
- Update the version in pearlcertification.public_api.client.PublicApiClient.get_url to the new version
Under "pearlcertification/api/views.py" replace the redirect url to the latest version
Update the version and the viewname in "pearlcertification.home_batches.preprocessing.assets.thermostat.Thermostat.get_url" to the new version
Update the version and the viewname in "pearlcertification.home_batches.preprocessing.assets.filter.Filter.get_url" to the new version
Add another section for the new version specifying the added features and changes
Update clients in equity calculator project to point to the corresponding urls of the newly created version.

1.1. Audit API changes

Starting from v4.20 of the pearl project, we added the Audit API as a way to get a snapshot of a home data at a certain point in time. The API relies on the Pearl API serializers and data mappers to serialize the home data to json. Still, we have yet to clearly define how the API will be used by contractors/programs, so until that is done we will keep updating its v1.0.0 with every new Pearl API version (we are not creating a new version). Once its purpose is clearly defined, and it is exposed to API consumers we will, we will start creating a v1.1.0, v2.0.0 as necessary.

1.1.1. Steps for adding a new version of the Audit API in case of a new release of the public api

Audit API serializer is using a dictionary named assets_utils which contains models, serializers and datamappers used in the public api to generate its fields dynamically. We will need to create a new dictionary with the new serializers/datamappers we have in the new version of public api.

Go to Snapshot model and add a new choice with the new Audit API version to the version field.
Go to pearlcertification.api.audit.base.asset_utils you’ll find a list of objects for each asset category. If you need to make a change in an asset category, create a new list for it to add the new serializer/datamapper classes from public api under the new version package in a new file vx/asset_utils.py, then create a new assets_utils dictionary to update it with the new lists created. The new assets_utils name should follow the following rule : assets_utils_vx where x is the new audit api version.
Go to pearlcertification.api.audit.version_manager, add to the utils_dict attribute a new key with the new version token having as value a dictionary containing the new assets_utils you created, if you didn’t make any change in AuditSerializer and AuditData classes you can keep them the same as the previous version.
Please keep in mind that there is a case not covered by the current implementation: If the change in public api is about adding/editing a MethodSerializerField it may trigger an error. If that is the case, consider making the change manually (check the implementation of score and level fields in HomeInfo and audit.base.serializers.HomeDetailsSerializer)
add new version urls to pearlcertification.audit.urls.

1.2. Changes included v6.2

1.2.1. New Features

Add choice cold_climate_air_source to type field for the HeatPumpSystems asset type
Add the field have_efficient_fan_controller to the HeatPumpSystems asset type with respective choices yes, no, unknown.
Add the fields have_efficient_fan_controller to the CoolingSystems asset type with respective choices yes, no, dont_know.
Field is allowed to be populated only if Heat Pump Type is set to Air Source, Cold Climate Air Source or Ground Source.
Add choice lithium_iron_phosphate to type field for the SolarEnergyStorage asset type
Add the field have_efficient_fan_controller to the HeatingSystem asset type with respective choices yes, no, unknown.
Field is allowed to be populated only if Heating System primary_heating_fuel is set to gas, electricity, oil or propane and type is set to central_furnace, room_furnace_through_the_wall or furnace.

1.3. Changes included v6.1

1.3.1. New Features

Add endpoint homes/{home_id}/specific_utility_plan_providers/ to list available specific utility plan providers.
Add is_energy_storage_included boolean field to Solar Panel & Array asset.
Add utility_plan_type field to Solar Panel & Array asset with choices average_utility_rate and specific_utility_plan.
Add specific_utility_plan_provider field to Solar Panel & Array asset. This field should be only set if utility_plan_type is set to specific_utility_plan. Provider’s name should be fetched from the list returned by homes/{home_id}/specific_utility_plan_providers/ endpoint.
Add specific_utility_plan field to Solar Panel & Array asset that includes to the utility plan external id. This field should be only set if utility_plan_type is set to specific_utility_plan. Plan’s external_id should be fetched from the list of plans corresponding to the provider set in specific_utility_plan_provider field. homes/{home_id}/specific_utility_plan_providers/ endpoint.
Add energy_bills field to Solar Panel & Array asset that list the monthly energy bills (date and power). The list must contain 12 items with 12 consecutive months dates.
Add specific_utility_plan_name read only field to Solar Panel & Array asset. homes/{home_id}/specific_utility_plan_providers/ endpoint should be used to get this value.
Add specific_utility_plan_uri read only field to Solar Panel & Array asset. homes/{home_id}/specific_utility_plan_providers/ endpoint should be used to get this value.
Add specific_utility_plan_is_default read only field to Solar Panel & Array asset. homes/{home_id}/specific_utility_plan_providers/ endpoint should be used to get this value.

1.4. Changes included v6

1.4.1. New Features

Add the field equipment_type to the PoolPump asset type with choices pool_pump, pool_heater
Add the field pool_heater_fuel_type to the PoolPump asset type with choices electric, heat_pump, solar, gas
Add the field backup_system_fuel_type to the PoolPump asset type with choices electricity, gas, oil, propane, kerosene
Change type field name to pool_pump_type.
pool_pump_type, horsepower, flow_rate, energy_factor fields are populated only if equipment_type is set to pool_pump.
pool_heater_fuel_type field is populated only if equipment_type is set to pool_heater.
backup_system_fuel_type field is populated only if pool_heater_fuel_type is set to solar.
Add endpoints to Create, Update, Retrieve and Delete the new Fireplace asset under the Baseload category.
Add the fields is_permanent and location to the CookingAppliance asset type with respective choices yes, no and indoor, outdoor.
Both fields are allowed to be populated only if Cooking appliance type? is set to range or cooktop.
For WaterHeating asset type add water_heater_type question with choices conventional_water_heater and indirect
Add the fields drying_machine_fuel to the ClothesDryer asset type with respective choices electric, heat_pump, gas.

1.4.2. Backward incompatible changes

rename the PoolPump asset type to PoolEquipment and change its url from pool_pumps/ to pool_equipment/

1.5. Changes included v5

1.5.1. New Features

Files with category=green-door-shared-doc are now automatically tagged with GD.
For firms configured with only one collateral package, certification requests created without a collateral package will have the collateral package set automatically.
add 4 new asset endpoints: kitchen_fixtures, bathroom_fixtures, cooking_appliances and ventilation.
add the year_manufactured field to the following asset endpoints: refrigerators, dishwashers, clothes_washers and clothes_dryers.
add proper_combustion_safety_testing and water_filtration_system to the health_and_indoor_air_quality asset endpoint.
add appliances_with_smart_features to the smart_home_devices asset endpoint.

1.5.2. Backward incompatible changes

remove nyserda_contractor from system_type choices in the external_identifiers endpoint
remove the nabcep_accredited_company field from the solar_installations endpoint

1.6. Changes included v4.2

1.6.1. New Features

add a new field auto_create_service_professional_information_asset to cert_request endpoint
based on this field we decide whether to auto create a service professional information asset or not

1.7. Changes included v4.1

1.7.1. New Features

add new endpoints for solar valuation adjustments.
add new choices sunpower_master_dealer, sunpower_non_installing_dealer, sunpower_elite, sunpower_authorized_dealer to the service_professional field in the Service Professional Information (spi) endpoint.
add new field radon_mitigation_features to the health_and_indoor_air_quality endpoint
add new field radon_levels_monitoring_and_reporting to the smart_home_devices endpoint

1.8. Changes included v4

1.8.1. Backward incompatible changes

In the power_production_warranty endpoint, change the field name annual_degradation_factor to degradation_rate_year_two and update the field label from Annual Degradation Factor? to Degradation Rate in Year Two Until End of Warranty?
- In the same endpoint, add a field name degradation_rate_year_one
- In the solar_inverters endpoint, add two fields with the names model_number and efficiency_rate respectively.
add a new optional “source” field to the create homes endpoint (POST /homes)
add new endpoints for solar_valuation to return the current estimated value of the home’s solar system
In the solar_panels_and_arrays endpoint:
- add a financed option to the ownership field and remove the option solar_loan_with_ucc_filing.
- add a new field financing_type that should be used only when ownership is set as financed.
- solar_loan_with_ucc_filing will be an option under financing_type.
- add a new field array_type that replaces mount and location.

1.8.2. New Features

add a new option owens_corning_air_care to the service_professional field in the spi endpoint
add a new option bpi_infiltration_and_duct_leakage_certification to the credentials field in the spi endpoint
add a new field model_number for solar_panels_and_arrays.
add advanced fields for calculating losses for solar_panels_and_arrays: soiling, shading, snow, mismatch, wiring, connections, light_induced_degradation, nameplate_rating, availability.
The year_built field now allows values until the next year.
add new fields model_number and efficiency_rate to the solar_inverters endpoint
add the ability to authenticate using JWT

1.9. Changes included v3

1.9.1. New Features

add the maintenance_templates endpoint for listing the maintenance templates created by a firm
add the assigned_maintenance_templates endpoint for assigning/removing maintenance templates to/from a home

1.9.2. Backward incompatible changes

Update the choices for premier_package_asset field from yes and no to 12_year, 10_year, no and unknown. This affects the following endpoints:
- heat_pumps
- heating_systems
- cooling_systems
- smart_home_devices
- health_and_indoor_air_quality
allow submitting premier_package_asset and model_name only for Lennox dealers in the following endpoints:
- heat_pumps
- heating_systems
- cooling_systems
- smart_home_devices
- health_and_indoor_air_quality
In the solar_panels_and_arrays endpoint, change the field name roof_installation to is_solar_roofing_tiles and update the field label from Is this a solar roof installation? to Is this a solar tile/roof installation?

1.9.3. Other changes

update the label for indoor_manufacturer field in heat_pumps and cooling_systems endpoints from Indoor Manufacturer to Indoor Unit Manufacturer
update the label for outdoor_manufacturer field in heat_pumps and cooling_systems endpoints from Outdoor Manufacturer to Outdoor Unit Manufacturer

1.10. Changes included v2

1.10.1. New Features

add the fiberglass option for the framing field in the windows_and_skylights endpoint
add green-door-shared-doc category for files shared with homeowners and add validation for setting this category based on the firm permission to issue green door logins
add roof_installation field to the Solar Panel & Array endpoint
add new questions to energy_storage endpoint: installer, installation_warranty_term, model_number, power_rating, round_trip_efficiency, guaranteed_capacity
add new field passive_cooling_architecture_plan to cooling_systems endpoint
add manufacturer field to the attic_insulation, wall_insulation, floor_and_foundation,rim_joist,door,windows_and_skylights,distribution_systems endpoints
add new choices to filtration_efficiency in health_and_indoor_air_quality endpoint. The new choices are: merv9 merv14 merv15 merv16 and electronic_air_cleaner.
add new field non_ozone_generating_uv_light to health_and_indoor_air_quality endpoint.
add field with choices smart_conditioning_control_system to smart_home_devices endpoint choices are:yes, no and unknown
add multiselect field indoor_air_quality_smart_controls to the smart_home_devices endpoint choices are:in_full_bathroom, kitchen_hood_ventilation, whole_home_ventilation and unknown

1.10.2. Backward incompatible changes

rename the MHP tag to GD and add validation for tagging files for green door based on the firm permission to issue green door logins
remove the deprecated energy_management endpoint
change choices and add new ones to whole_house_ventilation in health_and_indoor_air_quality endpoint choices changed: intake_or_exhaust_ventilation -> exhaust_only erv_or_hrv -> balanced_energy_or_heat_recovery choices added: supply_only and balanced
remove field humidity_management from health_and_indoor_air_quality endpoint
change choices in control_device: smart_home_devices endpoint label is also changed from Home has a device to monitor and automatically control excessive: to Permanently affixed humidifier or dehumidifier installed: choices changed: humidity -> dehumidifier dryness -> humidifier

1.10.3. Other changes

update the label for warranty field in theenergy_storage endpoint from Warranty Term (years) to Manufacturer Warranty Term (years)

1.11. Changes included in v1.1

1.11.1. New Features

allow creating homes by submitting the full_address. It is now possible to create homes using either full_address OR address components.
add lennox fields (model_name, premier_package_asset) to the health_and_indoor_air_quality, heat_pumps, heating_systems, cooling_systems, smart_home_devices and energy_management endpoints.
add model and secondary_model to the heat_pumps endpoint. These fields are specific to ground heat pumps.
add indoor_manufacturer and outdoor_manufacturer to the heat_pumps endpoint. These fields are specific to mini-split heat pumps.
add indoor_manufacturer and outdoor_manufacturer to the cooling_systems endpoint.

1.11.2. Other changes

deprecate energy_management and add smart_home_devices as a replacement with the same functionality and behavior
allow certification_email_recipients to be empty to send the certification email to the default contact email of the firm (certification_requests endpoint)
allow creating contacts without an email (contacts endpoint)