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/rustac/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#![deny(
36    elided_lifetimes_in_paths,
37    explicit_outlives_requirements,
38    keyword_idents,
39    macro_use_extern_crate,
40    meta_variable_misuse,
41    missing_abi,
42    missing_debug_implementations,
43    missing_docs,
44    non_ascii_idents,
45    noop_method_call,
46    rust_2021_incompatible_closure_captures,
47    rust_2021_incompatible_or_patterns,
48    rust_2021_prefixes_incompatible_syntax,
49    rust_2021_prelude_collisions,
50    single_use_lifetimes,
51    trivial_casts,
52    trivial_numeric_casts,
53    unreachable_pub,
54    unsafe_code,
55    unsafe_op_in_unsafe_fn,
56    unused_crate_dependencies,
57    unused_extern_crates,
58    unused_import_braces,
59    unused_lifetimes,
60    unused_qualifications,
61    unused_results,
62    warnings
63)]
64
65#[cfg(feature = "client")]
66pub mod client;
67mod collections;
68mod conformance;
69mod error;
70mod fields;
71mod filter;
72mod item_collection;
73mod items;
74mod root;
75mod search;
76mod sort;
77mod url_builder;
78
79#[cfg(feature = "client")]
80pub use client::{BlockingClient, Client};
81pub use collections::Collections;
82pub use conformance::{
83    COLLECTIONS_URI, CORE_URI, Conformance, FEATURES_URI, FILTER_URIS, GEOJSON_URI,
84    ITEM_SEARCH_URI, OGC_API_FEATURES_URI,
85};
86pub use error::Error;
87pub use fields::Fields;
88pub use filter::Filter;
89pub use item_collection::{Context, ItemCollection};
90pub use items::{GetItems, Items};
91pub use root::Root;
92pub use search::{GetSearch, Search};
93pub use sort::{Direction, Sortby};
94pub use url_builder::UrlBuilder;
95
96/// Crate-specific result type.
97pub type Result<T> = std::result::Result<T, Error>;
98
99/// A STAC API Item type definition.
100///
101/// By default, STAC API endpoints that return [stac::Item] objects return every
102/// field of those Items. However, Item objects can have hundreds of fields, or
103/// large geometries, and even smaller Item objects can add up when large
104/// numbers of them are in results. Frequently, not all fields in an Item are
105/// used, so this specification provides a mechanism for clients to request that
106/// servers to explicitly include or exclude certain fields.
107pub type Item = serde_json::Map<String, serde_json::Value>;
108
109/// Return this crate's version.
110///
111/// # Examples
112///
113/// ```
114/// println!("{}", stac_api::version());
115/// ```
116pub fn version() -> &'static str {
117    env!("CARGO_PKG_VERSION")
118}
119
120#[cfg(not(feature = "client"))]
121use tracing as _;
122#[cfg(test)]
123use {geojson as _, tokio_test as _};
124#[cfg(all(not(feature = "client"), test))]
125use {mockito as _, tokio as _};
126
127// From https://github.com/rust-lang/cargo/issues/383#issuecomment-720873790,
128// may they be forever blessed.
129#[cfg(doctest)]
130mod readme {
131    macro_rules! external_doc_test {
132        ($x:expr) => {
133            #[doc = $x]
134            unsafe extern "C" {}
135        };
136    }
137
138    external_doc_test!(include_str!("../README.md"));
139}
stac_api/lib.rs

stac_api/
lib.rs
