API Update PR! (#172)

- **Split Dispatch into metadata and data**
- **Require microgrid_id for all requests**
- **Rename `id` -> `dispatch_id`**
- **Use common API name pattern for list request messages**
- **Rename request messages to match API name patterns**
- **Create request should return the new dispatch**
- **Add documentation about authentication and encryption**
- **Return the updated dispatch object**
- **Add extra response message for get requests**
- **Add response message to delete request**
- **Remove possibility to update dry_run and type fields**

Author: Marenz

RELEASE_NOTES.md

@@ -2,15 +2,20 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+In this release, we have made some changes to the API to improve the user experience and to fix some bugs.
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+* The dispatch message was split into into metadata and data.
+* `microgrid_id` is required for all requests.
+* `id` was renamed to `dispatch_id` in all requests.
+* Naming conventions were updated to match API projects.
+* The possibility to update the `dry_run` and `type` fields was removed.
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+* Create and Update request now returns the new dispatch object.
+* Documentation about authentication and encryption was added.
 
 ## Bug Fixes
 

proto/frequenz/api/dispatch/v1/dispatch.proto

@@ -53,63 +53,60 @@ import "frequenz/api/common/v1/microgrid/components/components.proto";
 // This API is designed for application developers in the energy sector who focus on the tasks of optimizing microgrid
 // electricity flows. Its design aims to be as developer-friendly as possible, requiring no prior knowledge in
 // electrical engineering and systems.
+//
+// #### Security
+//
+// ALL requests to this service must be signed. The key and signature
+// should be added to the request metadata (HTTP headers). The signature
+// should be computed using the HMAC-SHA256 algorithm and the user's secret key.
+//
+// ALL requests to this service must be made over HTTPS.
 service MicrogridDispatchService {
   // Returns a list of all dispatches
-  rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList);
+  rpc ListMicrogridDispatches(ListMicrogridDispatchesRequest) returns (ListMicrogridDispatchesResponse);
 
   // Create a new dispatch
-  rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);
+  rpc CreateMicrogridDispatch(CreateMicrogridDispatchRequest) returns (CreateMicrogridDispatchResponse);
 
   // Update a dispatch
-  rpc UpdateMicrogridDispatch(DispatchUpdateRequest) returns (google.protobuf.Empty);
+  rpc UpdateMicrogridDispatch(UpdateMicrogridDispatchRequest) returns (UpdateMicrogridDispatchResponse);
 
   // Get a single dispatch
-  rpc GetMicrogridDispatch(DispatchGetRequest) returns (Dispatch);
+  rpc GetMicrogridDispatch(GetMicrogridDispatchRequest) returns (GetMicrogridDispatchResponse);
 
   // Delete a given dispatch
-  rpc DeleteMicrogridDispatch(DispatchDeleteRequest) returns (google.protobuf.Empty);
+  rpc DeleteMicrogridDispatch(DeleteMicrogridDispatchRequest) returns (DeleteMicrogridDispatchResponse);
 }
 
-// Message representing one dispatch.
+// Represents a dispatches data, including its type, start time, duration, component selector,
 //
 // Timezone Note: Timestamps are in UTC. It is the responsibility of each microgrid to translate UTC
 // to its local timezone.
 message Dispatch {
-  // The dispatch identifier
-  uint64 id = 1;
-
-  // The microgrid identifier
-  uint64 microgrid_id = 2;
-
   // The dispatch type.
   // Contains user-defined information about what "type" of dispatch this is.
   // Downstream applications that consume the dispatch API are responsible for
   // understanding and processing this field.
-  string type = 3;
-
-  // The creation time in UTC
-  // This is set when a dispatch is created via the create request message
-  google.protobuf.Timestamp create_time = 4;
-
-  // The update time in UTC
-  // This is set when a dispatch is modified via the update request message
-  google.protobuf.Timestamp update_time = 5;
+  string type = 1;
 
-  // The start time in UTC
-  google.protobuf.Timestamp start_time = 6;
+  // The dispatch start time in UTC.
+  // For reoccuring dispatches this is when the first time execution occurs. When
+  // creating a dispatch, ensure that the starting timestamp is set to the current
+  // time or any future time. Timestamps earlier than the current time are not allowed.
+  google.protobuf.Timestamp start_time = 2;
 
   // Duration in seconds
-  uint32 duration = 7;
+  optional uint32 duration = 3;
 
-  // The component selector
-  ComponentSelector selector = 8;
+  // Dispatch microgrid component selector
+  ComponentSelector selector = 4;
 
   // The "active" status
   // An active dispatch is eligible for processing, either immediately or at a scheduled
   // time in the future, including recurring dispatches. If a dispatch is set to
   // inactive, it won't be processed even if it matches all other conditions, allowing
   // for temporary disabling of dispatches without deletion.
-  bool is_active = 9;
+  bool is_active = 5;
 
   // The "dry run" status
   // A dry run dispatch is executed for logging and monitoring purposes
@@ -118,13 +115,28 @@ message Dispatch {
   // actually affecting any component states.
   // Notably, a dispatch can be both "dry run" and "active," allowing for
   // the system to generate logs and observe behavior without making actual changes.
-  bool is_dry_run = 10;
+  bool is_dry_run = 6;
 
   // The dispatch payload
-  google.protobuf.Struct payload = 11;
+  google.protobuf.Struct payload = 7;
 
   // The recurrence rule
-  RecurrenceRule recurrence = 12;
+  RecurrenceRule recurrence = 8;
+}
+
+// Represents a dispatch, including its metadata
+message DispatchDetail {
+  // Unique identifier of the microgrid dispatch.
+  uint64 dispatch_id = 1;
+
+  // The dispatch data
+  Dispatch dispatch = 2;
+
+  // UTC Timestamp when the order was created.
+  google.protobuf.Timestamp create_time = 3;
+
+  // UTC Timestamp of the last update to the order.
+  google.protobuf.Timestamp modification_time = 4;
 }
 
 // Filter parameter for specifying multiple time intervals
@@ -287,7 +299,7 @@ message RecurrenceRule {
 }
 
 // Message for listing dispatches for a given microgrid, and an optional filter
-message DispatchListRequest {
+message ListMicrogridDispatchesRequest {
   // The microgrid ID
   uint64 microgrid_id = 1;
 
@@ -315,46 +327,28 @@ message DispatchFilter {
 }
 
 // A list of dispatches
-message DispatchList {
+message ListMicrogridDispatchesResponse {
   // The dispatches
-  repeated Dispatch dispatches = 1;
+  repeated DispatchDetail dispatches = 1;
 }
 
 // Message to create a new dispatch with the given attributes
-message DispatchCreateRequest {
+message CreateMicrogridDispatchRequest {
   // The microgrid identifier
   uint64 microgrid_id = 1;
 
-  // The type of dispatch
-  string type = 2;
-
-  // The start time
-  // When creating a dispatch, ensure that the starting timestamp is set to
-  // the current time or any future time.
-  // Timestamps earlier than the current time are not allowed.
-  google.protobuf.Timestamp start_time = 3;
-
-  // Duration in seconds
-  uint32 duration = 4;
-
-  // The component selector
-  ComponentSelector selector = 5;
-
-  // The "active" status
-  bool is_active = 6;
-
-  // The "dry run" status
-  bool is_dry_run = 7;
-
-  // The dispatch payload
-  google.protobuf.Struct payload = 8;
+  // Content of the dispatch to be created
+  Dispatch dispatch = 2;
+}
 
-  // The recurrence rule
-  RecurrenceRule recurrence = 9;
+// Response message for creating a new dispatch
+message CreateMicrogridDispatchResponse {
+  // The created dispatch
+  DispatchDetail dispatch = 1;
 }
 
 // Message to update the dispatch with the given ID, with the given attributes
-message DispatchUpdateRequest {
+message UpdateMicrogridDispatchRequest {
   // Message containing the updated dispatch attributes
   message DispatchUpdate {
     // Message containing the updated recurrence rule attributes
@@ -384,52 +378,79 @@ message DispatchUpdateRequest {
       repeated uint32 bymonths = 8;
     }
 
-    // The type of dispatch
-    optional string type = 1;
-
     // The start time
     // When updating a dispatch, ensure that the starting timestamp is set to
     // the current time or any future time.
     // Timestamps earlier than the current time are not allowed.
-    google.protobuf.Timestamp start_time = 2;
+    google.protobuf.Timestamp start_time = 1;
 
     // Duration in seconds
-    optional uint32 duration = 3;
+    optional uint32 duration = 2;
 
     // The component selector
-    ComponentSelector selector = 4;
+    ComponentSelector selector = 3;
 
     // The "active" status
-    optional bool is_active = 5;
-
-    // The "dry run" status
-    optional bool is_dry_run = 6;
+    optional bool is_active = 4;
 
     // The dispatch payload
-    google.protobuf.Struct payload = 7;
+    google.protobuf.Struct payload = 5;
 
     // The recurrence rule
-    RecurrenceRuleUpdate recurrence = 8;
+    RecurrenceRuleUpdate recurrence = 6;
   }
 
+  // ID of the microgrid
+  uint64 microgrid_id = 1;
+
   // The dispatch identifier
-  uint64 id = 1;
+  uint64 dispatch_id = 2;
 
   // Field mask specifying which fields should be updated
-  google.protobuf.FieldMask update_mask = 2;
+  google.protobuf.FieldMask update_mask = 3;
 
   // The updated dispatch attributes
-  DispatchUpdate update = 3;
+  DispatchUpdate update = 4;
+}
+
+// Response message for updating a dispatch
+message UpdateMicrogridDispatchResponse {
+  // The updated dispatch
+  DispatchDetail dispatch = 1;
 }
 
 // Message to get a single dispatch by its ID
-message DispatchGetRequest {
+message GetMicrogridDispatchRequest {
+  // The microgrid ID that the dispatch belongs to
+  uint64 microgrid_id = 1;
+
   // The dispatch identifier
-  uint64 id = 1;
+  uint64 dispatch_id = 2;
+}
+
+// Response message for getting a single dispatch
+message GetMicrogridDispatchResponse {
+  // The microgrid ID that the dispatch belongs to
+  uint64 microgrid_id = 1;
+
+  // The dispatch
+  DispatchDetail dispatch = 2;
 }
 
 // Message to delete a single dispatch by its ID
-message DispatchDeleteRequest {
+message DeleteMicrogridDispatchRequest {
+  // The microgrid ID that the dispatch belongs to
+  uint64 microgrid_id = 1;
+
   // The dispatch identifier
-  uint64 id = 1;
+  uint64 dispatch_id = 2;
+}
+
+// Response message for deleting a single dispatch
+message DeleteMicrogridDispatchResponse {
+  // The microgrid ID that the dispatch belonged to
+  uint64 microgrid_id = 1;
+
+  // The dispatch ID that was deleted
+  uint64 dispatch_id = 2;
 }