diff --git a/README.md b/README.md index 0d57e35..5324a85 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ This also uses `Rocket.toml` from the current working directory as configuration You can alternatively pass a set of environment variables instead. See `docker-compose.yml` for a list. -## API endpoint +## Status API Endpoint The `/` API endpoint provides the current statistical data of your solar panels once it has successfully logged into the cloud service using your credentials. @@ -92,9 +92,9 @@ There is no path and no query parameters, just: GET / ``` -### Response +### Status API Response -A response uses the JSON format and typically looks like this: +The response uses the JSON format and typically looks like this: ```json {"current_w":23.0,"total_kwh":6159.0,"last_updated":1661194620} @@ -104,7 +104,7 @@ This contains the current production power (`current_w`) in Watt, the total of produced energy since installation (`total_kwh`) in kilowatt-hour and the (UNIX) timestamp that indicates when the information was last updated. -### Error response +### (Status) API Error Response If the API endpoint is accessed before any statistical data has been retrieved, or if any other request than `GET /` is made, an error response is returned @@ -114,6 +114,26 @@ that looks like this: {"error":"No status found (yet)"} ``` +## Version API Endpoint + +The `/version` endpoint provides information of the current version and build +of the service. This can be used to check if it needs to be updated. +Again, there is no path and no query parameters, just: + +```http +GET /version +``` + +### Version API Response + +The response uses the JSON format and typically looks like this: + +```json +{"version":"0.2.1","timestamp":"2023-01-29T14:10:24.971748027Z","git_sha":"5cbc3a04","git_timestamp":"2023-01-16T20:18:20Z"} +``` + +(Build and git information may be out of date.) + ## Integration in Home Assistant To integrate the Solar Grabber service in your [Home Assistant](https://www.home-assistant.io/) diff --git a/src/lib.rs b/src/lib.rs index 4f03b4c..16a44d3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -79,6 +79,38 @@ async fn status() -> Result, Json> { .ok_or_else(|| Json(Error::from("No status found (yet)"))) } +/// The version information as JSON response. +#[derive(Debug, Serialize)] +#[serde(crate = "rocket::serde")] +struct VersionInfo { + /// The version of the build. + version: String, + /// The timestamp of the build. + timestamp: String, + /// The (most recent) git SHA used for the build. + git_sha: String, + /// The timestamp of the last git commit used for the build. + git_timestamp: String, +} + +impl VersionInfo { + /// Retrieves the version information from the environment variables. + fn new() -> Self { + Self { + version: String::from(env!("VERGEN_BUILD_SEMVER")), + timestamp: String::from(env!("VERGEN_BUILD_TIMESTAMP")), + git_sha: String::from(&env!("VERGEN_GIT_SHA")[0..8]), + git_timestamp: String::from(env!("VERGEN_GIT_COMMIT_TIMESTAMP")), + } + } +} + +/// Returns the version information. +#[get("/version", format = "application/json")] +async fn version() -> Result, Json> { + Ok(Json(VersionInfo::new())) +} + /// Default catcher for any unsuppored request #[catch(default)] fn unsupported(status: rocket::http::Status, _request: &Request<'_>) -> Json { @@ -92,7 +124,7 @@ fn unsupported(status: rocket::http::Status, _request: &Request<'_>) -> Json Rocket { rocket::build() - .mount("/", routes![status]) + .mount("/", routes![status, version]) .register("/", catchers![unsupported]) .attach(AdHoc::config::()) .attach(AdHoc::on_liftoff("Updater", |rocket| {