diff --git a/README.md b/README.md index daa2846..6c22a42 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,14 @@ ## Introduction -Frequenz gRPC API to propagate dispatches to microgrids. +Frequenz gRPC API for cloud/app-facing dispatch CRUD operations (create, update, +delete, list, get) on microgrid dispatches. -Also checkout the [high-level overview](https://github.com/frequenz-floss/frequenz-sdk-python/wiki/APIs-stack-and-repositories-structure) of the various api repositories and how they work together +This API is part of the Dispatch API split: + +- **[frequenz-api-dispatch-common](https://github.com/frequenz-floss/frequenz-api-dispatch-common)** (public): Shared proto message definitions +- **frequenz-api-dispatch** (public, this repo): Cloud/app-facing dispatch CRUD operations +- **[frequenz-api-hostdispatch](https://github.com/frequenz-io/frequenz-api-hostdispatch)** (private): Controller-facing dispatch operations (stream, status reporting) Dispatches might include, for example: @@ -17,8 +22,8 @@ Dispatches might include, for example: * Activation or deactivation of balancing power * Activation or deactivation of a power plant -Microgrid controllers are expected to regularly query this API to keep up to -date with what resources the cloud wishes them to deploy. +Microgrid controllers should use the `HostDispatchService` for streaming and +status reporting. Application-level clients use this API for CRUD operations. ## Contributing diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 17459f5..1caff50 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -3,3 +3,7 @@ ## Summary This is the v1.0.0 release. It is equivalent to v1.0.0-rc3 and introduces a period of API stabilization. + +## Upcoming + +- Removing `StreamMicrogridDispatches` RPC - moved to the new `frequenz-api-hostdispatch` private repo. diff --git a/proto/frequenz/api/dispatch/v1/dispatch.proto b/proto/frequenz/api/dispatch/v1/dispatch.proto index a52e295..31d302e 100644 --- a/proto/frequenz/api/dispatch/v1/dispatch.proto +++ b/proto/frequenz/api/dispatch/v1/dispatch.proto @@ -19,7 +19,6 @@ import "google/protobuf/timestamp.proto"; import "frequenz/api/common/v1alpha8/microgrid/electrical_components/electrical_components.proto"; import "frequenz/api/common/v1alpha8/pagination/pagination_info.proto"; import "frequenz/api/common/v1alpha8/pagination/pagination_params.proto"; -import "frequenz/api/common/v1alpha8/streaming/event.proto"; import "frequenz/api/common/v1alpha8/types/interval.proto"; // Service providing operations related to dispatching microgrid components. @@ -64,13 +63,19 @@ import "frequenz/api/common/v1alpha8/types/interval.proto"; // should be computed using the HMAC-SHA256 algorithm and the user's secret key. // // ALL requests to this service must be made over HTTPS. +// +// !!! note "Streaming & Status Reporting" +// Real-time dispatch streaming and status reporting have moved to the +// [HostDispatch API](https://github.com/frequenz-io/frequenz-api-hostdispatch) +// (private, controller-only). Use `HostDispatchService` for: +// - `StreamMicrogridDispatches` — real-time dispatch updates for controllers +// - `ReportMicrogridDispatchStatus` — dispatch execution status reporting +// - `ListMicrogridDispatches` / `GetMicrogridDispatch` (also available here +// for cloud/app access with application API keys) service MicrogridDispatchService { // Returns a list of all dispatches rpc ListMicrogridDispatches(ListMicrogridDispatchesRequest) returns (ListMicrogridDispatchesResponse); - // Streaming RPC for receiving dispatch updates for a given microgrid - rpc StreamMicrogridDispatches(StreamMicrogridDispatchesRequest) returns (stream StreamMicrogridDispatchesResponse); - // Create a new dispatch rpc CreateMicrogridDispatch(CreateMicrogridDispatchRequest) returns (CreateMicrogridDispatchResponse); @@ -84,24 +89,6 @@ service MicrogridDispatchService { rpc DeleteMicrogridDispatch(DeleteMicrogridDispatchRequest) returns (DeleteMicrogridDispatchResponse); } -// Subscribe to a stream of microgrid dispatch requests. -// This method provides real-time updates on newly or updated dispatch requests for edge-based -// realtime decision making. -message StreamMicrogridDispatchesRequest { - // ID of the microgrid to subscribe to - uint64 microgrid_id = 1; -} - -// Response to a subscription request for a stream of microgrid dispatches. -// Real-time information on dispatches affecting a certain microgrid are pushed through this response. -message StreamMicrogridDispatchesResponse { - // Dispatch record returned. - Dispatch dispatch = 1; - - // Which event this response was triggered by - frequenz.api.common.v1alpha8.streaming.Event event = 2; -} - // Represents a dispatches data, including its type, start time, duration, // and target microgrid components. //