icinga2_api/types/rest.rs
1//! Rest API request related types
2//!
3//! (as opposed to the streaming event long-polling API parts)
4
5/// a trait for objects describing a REST API endpoint
6///
7/// this is implemented by types which contain all the necessary information
8/// for a request.
9pub trait RestApiEndpoint {
10 /// the type of the request body
11 type RequestBody;
12
13 /// returns the HTTP method to use
14 ///
15 /// since this is Icinga this is the method passed to X-HTTP-Method-Override
16 ///
17 /// the actual HTTP method will always be POST if there is a request body
18 ///
19 /// # Errors
20 ///
21 /// this should return an error if something went wrong in determining the request method
22 fn method(&self) -> Result<reqwest::Method, crate::error::Error>;
23
24 /// returns the URL to use for the request based on the base URL passed in
25 /// as a parameter
26 ///
27 /// # Errors
28 ///
29 /// this should return an error if something went wrong in determining the URL (e.g. parse error on the fragment joined to the base URL)
30 fn url(&self, base_url: &url::Url) -> Result<url::Url, crate::error::Error>;
31
32 /// the request body which must be a JSON serializable type
33 ///
34 /// since it is always JSON we do not need to return a Content-Type
35 ///
36 /// # Errors
37 ///
38 /// this should return an error if something went wrong in determining the request body
39 fn request_body(
40 &self,
41 ) -> Result<Option<std::borrow::Cow<Self::RequestBody>>, crate::error::Error>
42 where
43 Self::RequestBody: Clone + serde::Serialize + std::fmt::Debug;
44}
45
46/// this is a marker trait that marks a type as a valid response type for a
47/// given RestApiEndpoint
48pub trait RestApiResponse<ApiEndpoint> {}