stac_api/
lib.rs

1//! Rust implementation of the [STAC API](https://github.com/radiantearth/stac-api-spec) specification.
2//!
3//! This crate **is**:
4//!
5//! - Data structures
6//!
7//! This crate **is not**:
8//!
9//! - A server implementation
10//!
11//! For a STAC API server written in Rust based on this crate, see our
12//! [stac-server](https://github.com/stac-utils/stac-rs/tree/main/stac-server).
13//!
14//! # Data structures
15//!
16//! Each API endpoint has its own data structure. In some cases, these are
17//! light wrappers around [stac] data structures. In other cases, they can be
18//! different -- e.g. the `/search` endpoint may not return [Items](stac::Item)
19//! if the [fields](https://github.com/stac-api-extensions/fields) extension is
20//! used, so the return type is a crate-specific [Item] struct.
21//!
22//! For example, here's the root structure (a.k.a the landing page):
23//!
24//! ```
25//! use stac::Catalog;
26//! use stac_api::{Root, Conformance, CORE_URI};
27//! let root = Root {
28//!     catalog: Catalog::new("an-id", "a description"),
29//!     conformance: Conformance {
30//!         conforms_to: vec![CORE_URI.to_string()]
31//!     },
32//! };
33//! ```
34
35#![cfg_attr(docsrs, feature(doc_auto_cfg))]
36#![deny(
37    elided_lifetimes_in_paths,
38    explicit_outlives_requirements,
39    keyword_idents,
40    macro_use_extern_crate,
41    meta_variable_misuse,
42    missing_abi,
43    missing_debug_implementations,
44    missing_docs,
45    non_ascii_idents,
46    noop_method_call,
47    rust_2021_incompatible_closure_captures,
48    rust_2021_incompatible_or_patterns,
49    rust_2021_prefixes_incompatible_syntax,
50    rust_2021_prelude_collisions,
51    single_use_lifetimes,
52    trivial_casts,
53    trivial_numeric_casts,
54    unreachable_pub,
55    unsafe_code,
56    unsafe_op_in_unsafe_fn,
57    unused_crate_dependencies,
58    unused_extern_crates,
59    unused_import_braces,
60    unused_lifetimes,
61    unused_qualifications,
62    unused_results,
63    warnings
64)]
65
66#[cfg(feature = "client")]
67pub mod client;
68mod collections;
69mod conformance;
70mod error;
71mod fields;
72mod filter;
73mod item_collection;
74mod items;
75#[cfg(feature = "python")]
76pub mod python;
77mod root;
78mod search;
79mod sort;
80mod url_builder;
81
82#[cfg(feature = "client")]
83pub use client::{BlockingClient, Client};
84pub use collections::Collections;
85pub use conformance::{
86    Conformance, COLLECTIONS_URI, CORE_URI, FEATURES_URI, FILTER_URIS, GEOJSON_URI,
87    ITEM_SEARCH_URI, OGC_API_FEATURES_URI,
88};
89pub use error::Error;
90pub use fields::Fields;
91pub use filter::Filter;
92pub use item_collection::{Context, ItemCollection};
93pub use items::{GetItems, Items};
94pub use root::Root;
95pub use search::{GetSearch, Search};
96pub use sort::{Direction, Sortby};
97pub use url_builder::UrlBuilder;
98
99/// Crate-specific result type.
100pub type Result<T> = std::result::Result<T, Error>;
101
102/// A STAC API Item type definition.
103///
104/// By default, STAC API endpoints that return [stac::Item] objects return every
105/// field of those Items. However, Item objects can have hundreds of fields, or
106/// large geometries, and even smaller Item objects can add up when large
107/// numbers of them are in results. Frequently, not all fields in an Item are
108/// used, so this specification provides a mechanism for clients to request that
109/// servers to explicitly include or exclude certain fields.
110pub type Item = serde_json::Map<String, serde_json::Value>;
111
112/// Return this crate's version.
113///
114/// # Examples
115///
116/// ```
117/// println!("{}", stac_api::version());
118/// ```
119pub fn version() -> &'static str {
120    env!("CARGO_PKG_VERSION")
121}
122
123#[cfg(not(feature = "client"))]
124use tracing as _;
125#[cfg(test)]
126use {geojson as _, tokio_test as _};
127#[cfg(all(not(feature = "client"), test))]
128use {mockito as _, tokio as _};
129
130// From https://github.com/rust-lang/cargo/issues/383#issuecomment-720873790,
131// may they be forever blessed.
132#[cfg(doctest)]
133mod readme {
134    macro_rules! external_doc_test {
135        ($x:expr) => {
136            #[doc = $x]
137            extern "C" {}
138        };
139    }
140
141    external_doc_test!(include_str!("../README.md"));
142}
stac_api/lib.rs

stac_api/
lib.rs
