Skip to content

Commit 55b9b10

Browse files
danuwdanuw
authored
Merge pull request #532 from Green-Software-Foundation/wattime-v3-support
Watt Time v3 Support
2 parents 4f5dbd2 + 903a58f commit 55b9b10

File tree

43 files changed

+1017
-554
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1017
-554
lines changed

‎CHANGELOG.md

+63
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,69 @@
22

33
All notable changes to the Carbon Aware SDK will be documented in this file.
44

5+
## [1.5.0] - 2024-05
6+
7+
This is the WattTime v3 update. Most notable changes that may require action are for deployment configuration, and these are minor.
8+
9+
### Added
10+
11+
WattTime v3 API support. This is an inplace upgrade for v2.
12+
13+
### Removed
14+
15+
WattTime v2 API support due to v3 in place replacement.
16+
17+
### Fixed
18+
19+
-[#535] [Bug]: Configuration for locations loads twice](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/535)
20+
21+
### Changed
22+
23+
Updates for WattTime v3 API endpoint from v2, details in the [ADR for WattTime v3 changes](./casdk-docs/docs/architecture//decisions/0016-watt-time-v3.md).
24+
25+
#### API
26+
27+
No changes
28+
29+
#### API Deployment
30+
31+
Due to the change for WattTime v3, there is change to the configuration for WattTime users.
32+
33+
With some of the changes to the code, some of the configuration will also needs to change.
34+
35+
| Config (v2) | Config (v3) | Description |
36+
|------------------------------------|----------------------------------|------------------------------|
37+
| `BalancingAuthorityCacheTTL` | `RegionCacheTTL` | This is the cache for regions data in seconds, and has a default value of 1 day. This only needs updating if you set it |
38+
| n/a | `AuthenticationBaseUrl` | **NEW** This is the base URL for the WattTime Authentication API and defaults to `https://api.watttime.org/` if not set. |
39+
40+
Example below if set (note they do not have to be set)
41+
```json
42+
"wattTime_no-proxy": {
43+
"Type": "WattTime",
44+
"Username": "the_username",
45+
"Password": "super_secret_secret",
46+
"BaseURL": "https://api.watttime.org/v3/",
47+
"AutenticationBaseURL": "https://api.watttime.org", // This is new but not mandatory in config
48+
"RegionCacheTTL": 86400, // This is changed but not mandatory in config
49+
"Proxy": {
50+
"UseProxy": false
51+
}
52+
```
53+
54+
#### SDK
55+
56+
No changes
57+
58+
59+
#### Other
60+
61+
No changes
62+
63+
64+
For more details, checkout [https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/503](https://github.com/Green-Software-Foundation/carbon-aware-sdk/issues/503)
65+
66+
67+
568

669
## [1.4.0] - 2024-05
770

‎casdk-docs/docs/architecture/decisions/0016-watt-time-v3.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
2+
# 0015. WattTime v3 Changes
3+
4+
## Status
5+
6+
Proposed
7+
8+
## Context
9+
As part of the update to Watt Time v3 we are proposing the changes to the underlying API calls. This needs to be tracked so we understand the impacts, and if multiple options are available, which option was selected and why.
10+
11+
This wll impact the `CarbonAware.DataSources.WattTime` project primarily - however all test will need changing where there are downstream tests that are impacted, and for example, if any initialization needs reconfiguring it will impact dependency injection and likely `Program.cs` in the WattTime API projects.
12+
13+
## Decision
14+
15+
The proposal is for the outlined WattTime API mapping and changes.
16+
17+
## WattTime v2, v3 Mapping
18+
19+
The following document and guidelines was used to understand the impact to the Carbon Aware SDK for the WattTime v3 updates. https://docs.watttime.org/#tag/Transitioning-from-APIv2-to-APIv3
20+
21+
### Base URL
22+
The base URL will need to change. This is configured in the `appsettings.config` and can be set from environment variables.
23+
24+
|Base URL (v2) | Based URL (v3) |
25+
|---|---|
26+
| /v2 | /v3 |
27+
28+
29+
### Paths
30+
The paths will also need to change.
31+
32+
The following is configured at `CarbonAware.DataSources.WattTime/src/Constants/Paths.cs`
33+
34+
All response types for emission data include a response/data object, and a `meta` object which contains information such as `region`. As such historical data, forecast data, and historical forecast data objects will change significantly. These will be moved across to their own `...Response` record objects to abstract any future changes in the response type. Previously these objects had a lot of overlap so where the same class and this will cause significant rework of the code and tests, and breaking these out now will abstract them.
35+
36+
The `Login` is now at a different base URL, and to avoid any future issues a different HTTP client will be used for authentication, and the existing HTTP client will be used for API interaction. These will still sit in the `WattTimeClient` and as such no impacts to the dependent classes/logic.
37+
38+
| API Endpoint | Description | Path (v2) | Path (v3) | Notes |
39+
|--------------|-------------|-----------|-----------|---|
40+
| Data | Get data | /data | /historical | _Request_ <li> `starttime` is now `start` and mandatory <li> `endtime` is now `end` and mandatory <li> `ba` is now `region` <li> `signal_type` added <br> _Response_ <li> `signal_type` added
41+
| Forecast | Get forecast| /forecast | /forecast | <br> No longer be used for historical data <br> _Request_ <li> `ba` is now `region` <li> `extended_forecast` removed <li> `horizon_hours` added <li> `signal_type` added <li> Historical forecasts are now at `/forecast/historical` <br> _Response_ <li> `signal_type` added
42+
| Historical | Get historical forecast data | /historical (?) | /forecast/historical (?) | This changed signficantly. <br> _Request_ <li> `ba` is now `region` <li> `starttime` is now `start` and mandatory <li> `endtime` is now `end` and mandatory <li> `signal_type` added <br> _Response_ <li> `signal_type` added
43+
| Balancing Authority From Location | Get balancing authority from location | /ba-from-loc | /region-from-loc | Check if the CA SDK uses BA at all <br><br> _Request_ <li> `name` is now `region_full_name` <li> `abbrev` is now `region` <li> `signal_type` added <br> _Response_ <li> `id` removed <li> `signal_type` added |
44+
| Login | User login | https://api2.watttime.org/v2/login | https://api.watttime.org/login | Path has changed from being version specific to being no longer related to the API version. <br><br> Updated in `WattTimeClient` to now have 2 HTTP clients to decouple versions from the login.
45+
46+
### Query Strings
47+
48+
#### Signal Type
49+
Everything call takes an optional `signal_type` parameter that defaults to `co2_moer`.
50+
51+
The following comes from `CarbonAware.DataSources.WattTime/src/Constants/QueryStrings.cs` and the changes are consistent with the discussion above.
52+
53+
| Query String (v2) | Query String if Changed (v3) | Description |
54+
|------------------------------------|----------------------------------|------------------------------|
55+
| `ba` | `region` | Balancing Authority / Region |
56+
| `starttime` | `start` | Start Time |
57+
| `endtime` | `end` | End Time |
58+
| `latitude` | - | Latitude |
59+
| `longitude` | - | Longitude |
60+
| `username` | - | Username |
61+
62+
## Update Changes
63+
With some of the changes to the code, some of the configuration will also needs to change.
64+
65+
| Config (v2) | Config (v3) | Description |
66+
|------------------------------------|----------------------------------|------------------------------|
67+
| `BalancingAuthorityCacheTTL` | `RegionCacheTTL` | This is the cache for regions data in seconds, and has a default value of 1 day. |
68+
| n/a | `AuthenticationBaseUrl` | **NEW** This is the base URL for the WattTime Authentication API and defaults to `https://api.watttime.org/` if not set. |
69+
70+
Example below if set (note they do not have to be set)
71+
```json
72+
"wattTime_no-proxy": {
73+
"Type": "WattTime",
74+
"Username": "the_username",
75+
"Password": "super_secret_secret",
76+
"BaseURL": "https://api.watttime.org/v3/",
77+
"AutenticationBaseURL": "https://api.watttime.org", // This is new but not mandatory
78+
"RegionCacheTTL": 86400, // This is new but not mandatory
79+
"Proxy": {
80+
"UseProxy": false
81+
}
82+
```
83+
## Green Impact
84+
85+
Neutral
86+

‎casdk-docs/docs/tutorial-extras/carbon-aware-library.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -423,7 +423,7 @@ EmissionsForecast()
423423
#### Locations
424424

425425
Each WattTime emissions data point is associated with a particular named
426-
balancing authority. For transparency, this value is also used in
426+
region often referred to as a balancing authority. For transparency, this value is also used in
427427
`EmissionsData` response objects. It is not overwritten to match the named
428428
datacenter provided by any request.
429429

‎src/CarbonAware.CLI/test/integrationTests/Commands/EmissionsForecasts/EmissionsForecastsCommandTests.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ public async Task EmissionsForecasts_RequestedAtOptions_ReturnsExpectedData()
9999
IgnoreTestForDataSource("data source does not implement '--requested-at'", DataSourceType.ElectricityMaps);
100100

101101
// Arrange
102-
_dataSourceMocker.SetupBatchForecastMock();
102+
_dataSourceMocker.SetupHistoricalBatchForecastMock();
103103

104104
// Act
105105
var exitCode = await InvokeCliAsync($"emissions-forecasts -l eastus -r 2022-09-01");

‎src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/mock/ElectricityMapDataSourceMocker.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ public void SetupDataMock(DateTimeOffset start, DateTimeOffset end, string locat
126126
SetupResponseGivenGetRequest(Paths.PastRange, pastRange);
127127
}
128128

129-
public void SetupBatchForecastMock()
129+
public void SetupHistoricalBatchForecastMock()
130130
{
131131
throw new NotImplementedException();
132132
}

‎src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMaps/src/ElectricityMapsDataSource.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ private static EmissionsForecast ToEmissionsForecast(Location location, Forecast
7272
}
7373

7474
/// <inheritdoc />
75-
public async Task<EmissionsForecast> GetCarbonIntensityForecastAsync(Location location, DateTimeOffset requestedAt)
75+
public async Task<EmissionsForecast> GetHistoricalCarbonIntensityForecastAsync(Location location, DateTimeOffset requestedAt)
7676
{
7777
await Task.Run(() => true);
7878
throw new NotImplementedException();

‎src/CarbonAware.DataSources/CarbonAware.DataSources.ElectricityMapsFree/mock/ElectricityMapsFreeDataSourceMocker.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ public void SetupForecastMock()
4949
throw new NotImplementedException();
5050
}
5151

52-
public void SetupBatchForecastMock()
52+
public void SetupHistoricalBatchForecastMock()
5353
{
5454
throw new NotImplementedException();
5555
}

‎src/CarbonAware.DataSources/CarbonAware.DataSources.Json/mock/JsonDataSourceMocker.cs

+1-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ public void Initialize() { }
4242
public void Reset() { }
4343
public void Dispose() { }
4444

45-
public void SetupBatchForecastMock()
45+
public void SetupHistoricalBatchForecastMock()
4646
{
4747
throw new NotImplementedException();
4848
}

‎src/CarbonAware.DataSources/CarbonAware.DataSources.WattTime/mock/CarbonAware.DataSources.WattTime.Mocks.csproj

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313

1414
<ItemGroup>
1515
<ProjectReference Include="..\src\CarbonAware.DataSources.WattTime.csproj" />
16+
<ProjectReference Include="..\test\CarbonAware.DataSources.WattTime.Tests.csproj" />
1617
</ItemGroup>
1718

1819
<ItemGroup>

0 commit comments

Comments
 (0)