# 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.

## 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.

### 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`.

## Changes included v6.2
### 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`.

## Changes included v6.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.

## Changes included v6
### 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`.
  
### Backward incompatible changes
- rename the `PoolPump` asset type to `PoolEquipment` and change its url from `pool_pumps/` to `pool_equipment/`

## Changes included v5
### 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.

### 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

## Changes included v4.2
### 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

## Changes included v4.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

## Changes included v4
### 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`.

### 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

## Changes included v3
### 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

### 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?`

### 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`


## Changes included v2
### 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`

### 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`

### Other changes
- update the label for `warranty` field in the`energy_storage` endpoint from `Warranty Term (years)` to `Manufacturer Warranty Term (years)`


## Changes included in v1.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.

### 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)