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:
parent
de1ad37b95
commit
04e28a33c3
28
README.md
28
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
|
You can alternatively pass a set of environment variables instead. See
|
||||||
`docker-compose.yml` for a list.
|
`docker-compose.yml` for a list.
|
||||||
|
|
||||||
## API endpoint
|
## Status API Endpoint
|
||||||
|
|
||||||
The `/` API endpoint provides the current statistical data of your solar panels
|
The `/` API endpoint provides the current statistical data of your solar panels
|
||||||
once it has successfully logged into the cloud service using your credentials.
|
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 /
|
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
|
```json
|
||||||
{"current_w":23.0,"total_kwh":6159.0,"last_updated":1661194620}
|
{"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
|
the total of produced energy since installation (`total_kwh`) in kilowatt-hour
|
||||||
and the (UNIX) timestamp that indicates when the information was last updated.
|
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,
|
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
|
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)"}
|
{"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
|
## Integration in Home Assistant
|
||||||
|
|
||||||
To integrate the Solar Grabber service in your [Home Assistant](https://www.home-assistant.io/)
|
To integrate the Solar Grabber service in your [Home Assistant](https://www.home-assistant.io/)
|
||||||
|
|
34
src/lib.rs
34
src/lib.rs
|
@ -79,6 +79,38 @@ async fn status() -> Result<Json<Status>, Json<Error>> {
|
||||||
.ok_or_else(|| Json(Error::from("No status found (yet)")))
|
.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
|
/// Default catcher for any unsuppored request
|
||||||
#[catch(default)]
|
#[catch(default)]
|
||||||
fn unsupported(status: rocket::http::Status, _request: &Request<'_>) -> Json<Error> {
|
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.
|
/// Creates a Rocket and attaches the config parsing and update loop as fairings.
|
||||||
pub fn setup() -> Rocket<Build> {
|
pub fn setup() -> Rocket<Build> {
|
||||||
rocket::build()
|
rocket::build()
|
||||||
.mount("/", routes![status])
|
.mount("/", routes![status, version])
|
||||||
.register("/", catchers![unsupported])
|
.register("/", catchers![unsupported])
|
||||||
.attach(AdHoc::config::<Config>())
|
.attach(AdHoc::config::<Config>())
|
||||||
.attach(AdHoc::on_liftoff("Updater", |rocket| {
|
.attach(AdHoc::on_liftoff("Updater", |rocket| {
|
||||||
|
|
Loading…
Reference in New Issue