geeny-api 0.3.0

// Copyright 2017 Telefónica Germany Next GmbH. See the COPYRIGHT file at
// the top-level directory of this distribution
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

use reqwest::header;
use serde::de::DeserializeOwned;
use uuid::Uuid;

use endpoints::{DefaultClient, GeenyApi};
use errors::*;
use models::*;

/// Interface for Geeny Things Mangager APIs
///
/// `ThingsApi` is an interface for interacting with the Geeny Things Manager API.
/// The full specification of these APIs may be found in the
/// [API Specification](https://labs.geeny.io/things/docs/).
///
/// An explanation of what each of these Geeny items are (e.g. `ThingTypes`,
/// `MessageTypes`) may be found in the
/// [Geeny Glossary](https://confluence.geeny.io/display/EXTDOC/Geeny+ThingTypes+MessageTypes)
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct ThingsApi(GeenyApi);

impl Default for ThingsApi {
    /// Create a ThingsApi handle for the Production Things Manager
    ///
    /// # Example
    ///
    /// ```rust
    /// use geeny_api::ThingsApi;
    ///
    /// let api = ThingsApi::default();
    /// ```
    fn default() -> Self {
        Self::new("https://labs.geeny.io".into(), 443)
    }
}

impl ThingsApi {
    /// Create a new Things API handle
    ///
    /// If it is not necessary to set a custom host or port, the `default()`
    /// method may be used instead.
    ///
    /// # Example
    ///
    /// ```rust
    /// use geeny_api::ThingsApi;
    ///
    /// let api = ThingsApi::new("https://labs.geeny.io".into(), 443);
    /// ```
    pub fn new(host: String, port: u16) -> Self {
        ThingsApi(GeenyApi {
            host: host,
            port: port,
            client: DefaultClient::default(),
        })
    }

    /// Define a new MessageType on the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// use geeny_api::ThingsApi;
    /// use geeny_api::models::*;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     // Define a new MessageType to create
    ///     let mt_request = MessageTypeRequest {
    ///         name: "New MessageType".into(),
    ///         description: "Cool Test Message Type".into(),
    ///         media_type: "application/json".into(),
    ///         tags: vec![
    ///             "IoT".into(),
    ///             "Test".into(),
    ///             "Geeny".into(),
    ///         ],
    ///     };
    ///
    ///     let mt = api.create_message_type(&token, &mt_request).unwrap();
    /// }
    /// ```
    pub fn create_message_type(
        &self,
        token: &str,
        req: &MessageTypeRequest,
    ) -> Result<MessageType> {
        let mut rreq = self.0
            .client
            .0
            .post(&self.0.endpoint("/things/api/v1/messageTypes"));

        rreq.json(req);

        info!("Requesting: {:?}", rreq);
        rreq.header(header::Authorization(format!("JWT {}", token)));
        let mut resp = rreq.send()?;
        info!("Response: {:?}", resp);

        Ok(resp.json().chain_err(|| "Failed to deserialize")?)
    }

    /// Define a new ThingType on the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// extern crate uuid;
    /// use geeny_api::ThingsApi;
    /// use geeny_api::models::*;
    /// use uuid::Uuid;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     // Define a new ThingType to create
    ///     let tt_request = ThingTypeRequest {
    ///         name: "New ThingType".into(),
    ///         resources: vec![
    ///             Resource {
    ///                 uri: "demo/send/path".into(),
    ///                 method: ResourceMethod::Pub,
    ///                 message_type: Uuid::nil(), // 'id' field from `MessageType` struct
    ///             },
    ///             Resource {
    ///                 uri: "demo/receive/path".into(),
    ///                 method: ResourceMethod::Sub,
    ///                 message_type: Uuid::nil(), // 'id' field from `MessageType` struct
    ///             },
    ///         ],
    ///     };
    ///
    ///     let tt = api.create_thing_type(&token, &tt_request).unwrap();
    /// }
    /// ```
    pub fn create_thing_type(&self, token: &str, req: &ThingTypeRequest) -> Result<ThingType> {
        let mut rreq = self.0
            .client
            .0
            .post(&self.0.endpoint("/things/api/v1/thingTypes"));

        rreq.json(req);

        info!("Requesting: {:?}", rreq);
        rreq.header(header::Authorization(format!("JWT {}", token)));
        let mut resp = rreq.send()?;
        info!("Response: {:?}", resp);

        Ok(resp.json().chain_err(|| "Failed to deserialize")?)
    }

    /// Create a new instance of a Thing on the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// extern crate uuid;
    /// use geeny_api::ThingsApi;
    /// use geeny_api::models::*;
    /// use uuid::Uuid;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     // Define a new ThingType to create
    ///     let t_request = ThingRequest {
    ///         name: "New Thing".into(),
    ///
    ///         // Serial Number must be unique across all instances of...
    ///         serial_number: "ABCD12345".into(),
    ///
    ///         // ...this thing_type, from the `id` field of `ThingType` struct
    ///         thing_type: Uuid::nil(),
    ///     };
    ///
    ///     let thing = api.create_thing(&token, &t_request).unwrap();
    /// }
    /// ```
    pub fn create_thing(&self, token: &str, req: &ThingRequest) -> Result<Thing> {
        let mut rreq = self.0
            .client
            .0
            .post(&self.0.endpoint("/things/api/v1/things"));

        rreq.json(req);


        info!("Requesting: {:?}", rreq);
        rreq.header(header::Authorization(format!("JWT {}", token)));
        let mut resp = rreq.send()?;
        info!("Response: {:?}", resp);

        Ok(resp.json().chain_err(|| "Failed to deserialize")?)
    }

    /// Delete a specific Thing from the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// extern crate uuid;
    /// use geeny_api::ThingsApi;
    /// use uuid::Uuid;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     let thing = api.delete_thing(&token, &Uuid::nil()).unwrap();
    /// }
    /// ```
    pub fn delete_thing(&self, token: &str, id: &Uuid) -> Result<Thing> {
        let mut rreq = self.0.client.0.delete(&self.0
            .endpoint(&format!("/things/api/v1/things/{}", id.hyphenated())));



        info!("Requesting: {:?}", rreq);
        rreq.header(header::Authorization(format!("JWT {}", token)));
        let mut resp = rreq.send()?;
        info!("Response: {:?}", resp);

        Ok(resp.json().chain_err(|| "Failed to deserialize")?)
    }

    /// Get all publicly visible ThingTypes from the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// use geeny_api::ThingsApi;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     let all_thing_types = api.get_thing_types(&token).unwrap();
    ///
    ///     for tt in all_thing_types {
    ///         println!("{:?}", tt);
    ///     }
    /// }
    /// ```
    pub fn get_thing_types(&self, token: &str) -> Result<Vec<ThingType>> {
        get_all(&self.0, token, "/things/api/v1/thingTypes")
    }

    /// Get all publicly visible MessageTypes from the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// use geeny_api::ThingsApi;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     let all_message_types = api.get_message_types(&token).unwrap();
    ///
    ///     for mt in all_message_types {
    ///         println!("{:?}", mt);
    ///     }
    /// }
    /// ```
    pub fn get_message_types(&self, token: &str) -> Result<Vec<MessageType>> {
        get_all(&self.0, token, "/things/api/v1/messageTypes")
    }

    /// Get all Things from the current account from the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// use geeny_api::ThingsApi;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     let all_things = api.get_things(&token).unwrap();
    ///
    ///     for thing in all_things {
    ///         println!("{:?}", thing);
    ///     }
    /// }
    /// ```
    pub fn get_things(&self, token: &str) -> Result<Vec<Thing>> {
        get_all(&self.0, token, "/things/api/v1/things")
    }

    /// Get all Resources for a given ThingType from the Geeny Cloud
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// extern crate uuid;
    /// use geeny_api::ThingsApi;
    /// use uuid::Uuid;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     let resources = api.get_thing_type_resources(
    ///         &token,
    ///         &Uuid::nil() // from `id` field of `ThingType` struct
    ///     ).unwrap();
    ///
    ///     for resource in resources {
    ///         println!("{:?}", resource);
    ///     }
    /// }
    /// ```
    pub fn get_thing_type_resources(&self, token: &str, ttid: &Uuid) -> Result<Vec<Resource>> {
        get_all(
            &self.0,
            token,
            &format!("/things/api/v1/thingTypes/{}/resources", ttid.hyphenated()),
        )
    }

    /// Obtain a specific Thing from the current account from the Geeny Cloud
    /// by the Thing's serial number
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// extern crate geeny_api;
    /// use geeny_api::ThingsApi;
    ///
    /// fn main() {
    ///     let api = ThingsApi::default();
    ///     let token = "...".to_string(); // from ConnectApi
    ///
    ///     let thing = api.get_thing_by_serial(
    ///         &token,
    ///         "ABCD12345"
    ///     ).unwrap();
    /// }
    /// ```
    pub fn get_thing_by_serial(&self, token: &str, serial: &str) -> Result<Option<Thing>> {
        // TODO - filter server side to only get matching devices
        let things = self.get_things(token)?;
        let found = things.iter().find(|i| i.serial_number == serial);

        let thing = match found {
            Some(t) => Some(t.to_owned()),
            None => None,
        };

        Ok(thing)
    }
}

/// Generic method to get all T's from a given endpoint, following a standard
/// "paging" approach
fn get_all<T>(api: &GeenyApi, token: &str, endpoint: &str) -> Result<Vec<T>>
where
    T: DeserializeOwned,
{
    let mut response = vec![];

    loop {
        let url = format!("{}?offset={}", endpoint, response.len());

        let mut rreq = api.client.0.get(&api.endpoint(&url));


        info!("Requesting: {:?}", rreq);
        rreq.header(header::Authorization(format!("JWT {}", token)));
        let mut resp = rreq.send()?;
        info!("Response: {:?}", resp);

        let mut data_resp = resp.json::<GenericResponse<T>>()
            .chain_err(|| "Failed to deserialize")?;

        // Move all of the items from response into retval
        let len = data_resp.data.len();
        response.append(&mut data_resp.data);

        // If the response was not "full", we are done
        if len != data_resp.meta.limit {
            break;
        }
    }

    Ok(response)
}

#[cfg(test)]
mod test {
    use super::*;
    use serde_json;
    use models::*;

    #[test]
    fn serialize_test() {
        let api = ThingsApi::default();
        let s = serde_json::to_string(&api).unwrap();

        assert_eq!(s, "{\"host\":\"https://labs.geeny.io\",\"port\":443}");
    }

    #[test]
    fn deserialize_test() {
        let api = ThingsApi::default();
        let de_api: ThingsApi = serde_json::from_str(
            r#"
            {
                "host": "https://labs.geeny.io",
                "port": 443
            }
        "#,
        ).unwrap();

        assert_eq!(api.0.host, de_api.0.host);
        assert_eq!(api.0.port, de_api.0.port);
    }

    #[ignore]
    #[test]
    fn basic_test() {
        let token = get_token();
        let api = ThingsApi::default();

        assert!(api.get_things(&token).is_ok());
    }

    fn get_token() -> String {
        use std::env;
        use endpoints::connect::ConnectApi;

        let user = env::var("TEST_USER").unwrap();
        let pass = env::var("TEST_PASSWORD").unwrap();

        let api = ConnectApi::default();
        let req = AuthLoginRequest {
            email: user,
            password: pass,
        };

        api.login(&req).unwrap().token
    }
}