praiya/lib.rs
1//! [](https://crates.io/crates/praiya)
2//! [](https://opensource.org/licenses/Apache-2.0)
3//! [](https://docs.rs/praiya/)
4//! [](https://github.com/fussybeaver/praiya/actions/workflows/main.yml)
5//!
6//!
7//! # Praiya: an async PagerDuty API for Rust
8//!
9//! Praiya leverages the official [PagerDuty OpenAPI swagger
10//! specification](https://github.com/PagerDuty/api-schema) to generate models and mock server
11//! stubs, in order to closely match the real-world [PagerDuty
12//! API](https://developer.pagerduty.com/api-reference/) behaviour. Praiya's async paradigm runs on
13//! [Hyper](https://github.com/hyperium/hyper) and [Tokio](https://github.com/tokio-rs/tokio),
14//! tests are run against a [Prism](https://stoplight.io/open-source/prism) server that matches the
15//! OpenAPI specification responses.
16//!
17//! # Install
18//!
19//! Add the following to your `Cargo.toml` file.
20//!
21//! ```nocompile
22//! [dependencies]
23//! praiya = "*"
24//! ```
25//!
26//! # API
27//! ## Documentation
28//!
29//! [API docs](https://docs.rs/praiya/)
30//!
31//! Praiya has currently implemented the following API endpoints:
32//!
33//! - [ ] abilities
34//! - [ ] add_ons
35//! - [ ] analytics
36//! - [ ] audit
37//! - [ ] business_services
38//! - [X] escalation_policies
39//! - [ ] extension_schemas
40//! - [ ] extensions
41//! - [X] incidents
42//! - [ ] log_entries
43//! - [ ] maintenance_windows
44//! - [ ] notifications
45//! - [X] on_calls
46//! - [ ] priorities
47//! - [ ] response_plays
48//! - [ ] rulesets
49//! - [X] schedules
50//! - [ ] service_dependencies
51//! - [X] services
52//! - [X] slack_connections
53//! - [ ] tags
54//! - [ ] teams
55//! - [X] users
56//! - [ ] vendors
57//!
58//! # Usage
59//!
60//! ## Connecting to the PagerDuty API server
61//!
62//! A new `Praiya` client takes the PagerDuty API token and will build an SSL context:
63//!
64//! ```rust
65//! praiya::Praiya::new("PAGERDUTY_TOKEN");
66//!
67//! ```
68//!
69//! ## Examples
70//!
71//! ### Listing incidents
72//!
73//! To list triggered and acknowledged incidents in your organisation:
74//!
75//! ```rust,no_run
76//! use praiya::ParamsBuilder;
77//!
78//! use futures_util::TryStreamExt;
79//!
80//! let pagerduty = praiya::Praiya::new("PAGERDUTY_TOKEN");
81//!
82//! let mut opts_builder = praiya::endpoints::incidents::ListIncidentsParamsBuilder::new();
83//! opts_builder.statuses(vec!["triggered", "acknowledged"]);
84//! let opts = opts_builder.build();
85//!
86//! async move {
87//! let incidents: Vec<praiya::models::Incident> = pagerduty
88//! .incidents("from@example.com")
89//! .list_incidents(opts)
90//! .try_collect()
91//! .await
92//! .expect("Unable to list PagerDuty incidents");
93//! };
94//! ```
95//!
96//! # Development
97//!
98//! Contributions are welcome, please observe the following advice.
99//!
100//! ## Building the stubs
101//!
102//! Serialization stubs are generated through the [Swagger
103//! library](https://github.com/swagger-api/swagger-codegen/). To generate these files, use the
104//! following:
105//!
106//! ```bash
107//! mvn -D org.slf4j.simpleLogger.defaultLogLevel=debug compiler:compile generate-resources
108//! ```
109//!
110//! ## Mock test server
111//!
112//! The mock servers run with the [Prism](https://stoplight.io/open-source/prism) project against a
113//! [forked branch](https://github.com/fussybeaver/pagerduty-api-schema/tree/praiya-master) of the
114//! official PagerDuty API schema, in order to maintain stability of the Praiya CI pipelines.
115//!
116//! Mock servers are started with [Docker Compose](https://docs.docker.com/compose/):
117//!
118//! ```nocompile
119//! docker-compose up -d
120//! ```
121//!
122//! or alternatively use the npm library.
123//!
124//! ```nocompile
125//! npm install -g @stoplight/prism-cli
126//! # for example
127//! prism mock https://raw.githubusercontent.com/fussybeaver/pagerduty-api-schema/praiya-master/reference/REST/openapiv3.json
128//! ```
129//!
130//! ## Tests
131//!
132//! In order to run tests, point the client to the appropriate mock server:
133//!
134//! For the slack API:
135//!
136//! ```nocompile
137//! env PAGERDUTY_API_ENDPOINT=http://127.0.0.1:8080 RUST_LOG=praiya=debug cargo test slack
138//! ```
139//!
140//! For the default API's:
141//!
142//! ```nocompile
143//! env PAGERDUTY_API_ENDPOINT=http://127.0.0.1:8081 RUST_LOG=praiya=debug cargo test incidents
144//! env PAGERDUTY_API_ENDPOINT=http://127.0.0.1:8081 RUST_LOG=praiya=debug cargo test services
145//! ...
146//! ```
147//!
148//! ## Documentation
149//!
150//! This README is generated with [cargo-readme](https://github.com/livioribeiro/cargo-readme)
151//!
152//! ```nocompile
153//! cargo readme --no-title > README.md
154//! ```
155//!
156//! # License
157//!
158//! This software is licensed under the liberal [Apache License 2.0](https://opensource.org/licenses/Apache-2.0)
159//!
160#![allow(missing_docs, unused_imports)]
161
162#[macro_use]
163extern crate serde_derive;
164#[macro_use]
165mod macros;
166
167use std::collections::HashMap;
168
169#[rustfmt::skip]
170pub mod default_models;
171pub mod endpoints;
172pub mod errors;
173mod praiya;
174#[rustfmt::skip]
175pub mod slack_models;
176
177pub(crate) use crate::praiya::{
178 BaseOption, BaseRequest, PaginatedResponse, PaginationQueryComponent, SingleResponse, SubSystem,
179};
180pub use crate::praiya::{ParamsBuilder, Praiya, DEFAULT_PAGERDUTY_API_LIMIT};
181
182pub mod auth {
183 pub enum Auth {
184 Basic { user: String, pass: String },
185 Token(String),
186 Bearer(String),
187 None,
188 }
189}
190
191pub use default_models as models;
192pub use endpoints as api;