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#![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;
75mod root;
76mod search;
77mod sort;
78mod url_builder;
79
80#[cfg(feature = "client")]
81pub use client::{BlockingClient, Client};
82pub use collections::Collections;
83pub use conformance::{
84    COLLECTIONS_URI, CORE_URI, Conformance, FEATURES_URI, FILTER_URIS, GEOJSON_URI,
85    ITEM_SEARCH_URI, OGC_API_FEATURES_URI,
86};
87pub use error::Error;
88pub use fields::Fields;
89pub use filter::Filter;
90pub use item_collection::{Context, ItemCollection};
91pub use items::{GetItems, Items};
92pub use root::Root;
93pub use search::{GetSearch, Search};
94pub use sort::{Direction, Sortby};
95pub use url_builder::UrlBuilder;
96
97/// Crate-specific result type.
98pub type Result<T> = std::result::Result<T, Error>;
99
100/// A STAC API Item type definition.
101///
102/// By default, STAC API endpoints that return [stac::Item] objects return every
103/// field of those Items. However, Item objects can have hundreds of fields, or
104/// large geometries, and even smaller Item objects can add up when large
105/// numbers of them are in results. Frequently, not all fields in an Item are
106/// used, so this specification provides a mechanism for clients to request that
107/// servers to explicitly include or exclude certain fields.
108pub type Item = serde_json::Map<String, serde_json::Value>;
109
110/// Return this crate's version.
111///
112/// # Examples
113///
114/// ```
115/// println!("{}", stac_api::version());
116/// ```
117pub fn version() -> &'static str {
118    env!("CARGO_PKG_VERSION")
119}
120
121#[cfg(not(feature = "client"))]
122use tracing as _;
123#[cfg(test)]
124use {geojson as _, tokio_test as _};
125#[cfg(all(not(feature = "client"), test))]
126use {mockito as _, tokio as _};
127
128// From https://github.com/rust-lang/cargo/issues/383#issuecomment-720873790,
129// may they be forever blessed.
130#[cfg(doctest)]
131mod readme {
132    macro_rules! external_doc_test {
133        ($x:expr) => {
134            #[doc = $x]
135            unsafe extern "C" {}
136        };
137    }
138
139    external_doc_test!(include_str!("../README.md"));
140}
stac_api/lib.rs

stac_api/
lib.rs
