xo-api-client

Xen Orchestra through its API

Under development

The library is still in early development, please do not use in production. The API is nowhere near complete and only covers a very small fraction of XO's api. Lots of things might get changed and/or added in breaking ways at any time.

Async Runtime

This library uses the tokio v1 runtime

Example

Example of listing all VMs with the tag Test

use std::collections::BTreeMap;
use xo_api_client::{credentials::EmailAndPassword, Client, Vm, VmId};

// We dont care about any of the data under the "other" attribute
// in this example
#[derive(serde::Deserialize)]
struct OtherInfo {}

impl xo_api_client::vm::OtherInfo for OtherInfo {}

#[tokio::main]
async fn main() {
    let url = "ws://localhost:8080/api/";
    let email = String::from("[email protected]");
    let password = String::from("admin");

    let con = Client::connect(url)
        .await
        .expect("Failed to connect to server");
        
    con.sign_in(EmailAndPassword { email, password })
        .await
        .expect("Failed to sign in");

    let all_vms: BTreeMap<VmId, Vm<OtherInfo>> =
        con.get_vms(None, None).await.expect("Failed to list VMs");

    let test_vms = all_vms
        .iter()
        .filter(|(_id, vm)| vm.tags.iter().any(|tag| tag == "Test"));

    println!("All VMs with the tag 'Test':");
    for (id, vm) in test_vms {
        println!("ID: {:?}, Name: {}", id, vm.name_label);
    }
}

License

xo-api-client is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, and LICENSE-MIT for details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in xo-api-client by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

How close do we want to stay to xo-servers types?

There are quite a lot of examples of things in the types sent by xo-server that might make sense in javascript/json but less so in rust. To get out the most out of rusts strong type system some translations might be needed.

I believe there are atleast three categories of types:

stringly -> strict(er) types. One such example would be ip addresses. In the json object they are simply a string. In rust something like a std::net::IpAddr might make more sense. However, due to not all strings being valid IpAddr'es there is a dilemma - Do we know for a fact that xo-server always gives us valid ip addresses?
null/undefined -> empty map there are several examples in where xo-server sometimes uses null/undefined for a field and other times an object for that same field. This can be modeled in rust for example by using Option<HashMap<...>>. However it is not clear to me whether the distinction between {}, null and undefined in those cases is of importance. Perhaps something like the address field of Vm could be represented as a plain HasMap not wrapped in any option. This would make it more streamlined to work with. However this is technically a lossy conversion and because of this any serialization again could look different from the original.

TODO describe better and add more cases

Breaking