Add a /version API endpoint

* Introduce the `VersionInfo` struct, build from the vergen environment
  variables
* Add the `version` handler to construct and return the version info
* Update the README
This commit is contained in:
Paul van Tilburg 2023-01-29 15:29:32 +01:00
parent de1ad37b95
commit 04e28a33c3
Signed by: paul
GPG key ID: C6DE073EDA9EEC4D
2 changed files with 57 additions and 5 deletions

View file

@ -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/)

View file

@ -79,6 +79,38 @@ async fn status() -> Result<Json<Status>, Json<Error>> {
.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<VersionInfo>, Json<Error>> {
Ok(Json(VersionInfo::new()))
}
/// Default catcher for any unsuppored request
#[catch(default)]
fn unsupported(status: rocket::http::Status, _request: &Request<'_>) -> Json<Error> {
@ -92,7 +124,7 @@ fn unsupported(status: rocket::http::Status, _request: &Request<'_>) -> Json<Err
/// Creates a Rocket and attaches the config parsing and update loop as fairings.
pub fn setup() -> Rocket<Build> {
rocket::build()
.mount("/", routes![status])
.mount("/", routes![status, version])
.register("/", catchers![unsupported])
.attach(AdHoc::config::<Config>())
.attach(AdHoc::on_liftoff("Updater", |rocket| {