1  //! # Backstage Client Library
 2  //!
 3  //! A Rust client library for interacting with the Backstage Catalog API.
 4  //! This library provides type-safe access to Backstage entities and supports
 5  //! filtering, querying, and retrieving various entity types.
 6  //!
 7  //! ## Features
 8  //!
 9  //! - **Type-safe entities**: Strongly typed representations of all Backstage entity kinds
10  //! - **Async support**: Built on tokio and reqwest for modern async operations
11  //! - **Filtering**: Support for complex entity filtering using query parameters
12  //! - **Error handling**: Comprehensive error types with detailed error information
13  //! - **Authentication**: Bearer token authentication support
14  //!
15  //! ## Quick Start
16  //!
17  //! ```rust,no_run
18  //! use backstage_client::{BackstageClient, entities::Entity};
19  //! use std::collections::HashMap;
20  //!
21  //! #[tokio::main]
22  //! async fn main() -> Result<(), Box<dyn std::error::Error>> {
23  //!     let client = BackstageClient::new("https://backstage.example.com", "your-token")?;
24  //!
25  //!     // Fetch all entities
26  //!     let entities = client.fetch_entities::<Entity>(None).await?;
27  //!     println!("Found {} entities", entities.len());
28  //!
29  //!     // Fetch only components
30  //!     let mut filters = HashMap::new();
31  //!     filters.insert("kind".to_string(), "Component".to_string());
32  //!     let components = client.fetch_entities::<Entity>(Some(filters)).await?;
33  //!     println!("Found {} components", components.len());
34  //!
35  //!     Ok(())
36  //! }
37  //! ```
38  //!
39  //! ## Supported Entity Types
40  //!
41  //! - [`Component`](entities::Component) - Software components
42  //! - [`ApiEntity`](entities::ApiEntity) - API definitions
43  //! - [`ResourceEntity`](entities::ResourceEntity) - Infrastructure resources
44  //! - [`SystemEntity`](entities::SystemEntity) - System definitions
45  //! - [`GroupEntity`](entities::GroupEntity) - User groups
46  //! - [`UserEntity`](entities::UserEntity) - Individual users
47  //! - [`LocationEntity`](entities::LocationEntity) - Entity locations
48  //! - [`DomainEntity`](entities::DomainEntity) - Business domains
49  //! - [`TemplateEntity`](entities::TemplateEntity) - Software templates
50  
51  pub mod client;
52  pub mod entities;
53  pub mod error;
54  
55  // Re-export the main client and commonly used types
56  pub use client::BackstageClient;
57  pub use error::{ClientError, Result};
58  
59  // Re-export all entity types for convenience
60  pub use entities::{
61      ApiEntity, Component, DomainEntity, Entity, GroupEntity, LocationEntity, Metadata,
62      ResourceEntity, SystemEntity, TemplateEntity, UserEntity,
63  };
64  
65  // Re-export common types
66  pub use entities::common::{Relation, Target};
67  
68  #[cfg(test)]
69  mod tests {
70      use super::*;
71      use std::collections::HashMap;
72  
73      #[test]
74      fn test_library_exports() {
75          // Test that we can create a client
76          let client_result = BackstageClient::new("https://example.com", "token");
77          assert!(client_result.is_ok());
78  
79          // Test that we can create filters
80          let mut filters = HashMap::new();
81          filters.insert("kind".to_string(), "Component".to_string());
82  
83          // Test that error types are accessible
84          let _error: ClientError = ClientError::InvalidUrl("test".to_string());
85      }
86  }