1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
//! Rust implementation of the [STAC API](https://github.com/radiantearth/stac-api-spec) specification.
//!
//! This crate **is**:
//!
//! - Data structures
//!
//! This crate **is not**:
//!
//! - A server implementation
//!
//! For a STAC API server written in Rust based on this crate, see our
//! [stac-server](https://github.com/stac-utils/stac-rs/tree/main/stac-server).
//!
//! # Data structures
//!
//! Each API endpoint has its own data structure. In some cases, these are
//! light wrappers around [stac] data structures. In other cases, they can be
//! different -- e.g. the `/search` endpoint may not return [Items](stac::Item)
//! if the [fields](https://github.com/stac-api-extensions/fields) extension is
//! used, so the return type is a crate-specific [Item] struct.
//!
//! For example, here's the root structure (a.k.a the landing page):
//!
//! ```
//! use stac::Catalog;
//! use stac_api::{Root, Conformance, CORE_URI};
//! let root = Root {
//!     catalog: Catalog::new("an-id", "a description"),
//!     conformance: Conformance {
//!         conforms_to: vec![CORE_URI.to_string()]
//!     },
//! };
//! ```

#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![deny(
    elided_lifetimes_in_paths,
    explicit_outlives_requirements,
    keyword_idents,
    macro_use_extern_crate,
    meta_variable_misuse,
    missing_abi,
    missing_debug_implementations,
    missing_docs,
    non_ascii_idents,
    noop_method_call,
    rust_2021_incompatible_closure_captures,
    rust_2021_incompatible_or_patterns,
    rust_2021_prefixes_incompatible_syntax,
    rust_2021_prelude_collisions,
    single_use_lifetimes,
    trivial_casts,
    trivial_numeric_casts,
    unreachable_pub,
    unsafe_code,
    unsafe_op_in_unsafe_fn,
    unused_crate_dependencies,
    unused_extern_crates,
    unused_import_braces,
    unused_lifetimes,
    unused_qualifications,
    unused_results,
    warnings
)]

#[cfg(feature = "client")]
pub mod client;
mod collections;
mod conformance;
mod error;
mod fields;
mod filter;
mod item_collection;
mod items;
mod root;
mod search;
mod sort;
mod url_builder;

#[cfg(feature = "client")]
pub use client::{BlockingClient, Client};
pub use {
    collections::Collections,
    conformance::{
        Conformance, COLLECTIONS_URI, CORE_URI, FEATURES_URI, GEOJSON_URI, ITEM_SEARCH_URI,
        OGC_API_FEATURES_URI,
    },
    error::Error,
    fields::Fields,
    filter::Filter,
    item_collection::{Context, ItemCollection},
    items::{GetItems, Items},
    root::Root,
    search::{GetSearch, Search},
    sort::{Direction, Sortby},
    url_builder::UrlBuilder,
};

/// Crate-specific result type.
pub type Result<T> = std::result::Result<T, Error>;

/// A STAC API Item type definition.
///
/// By default, STAC API endpoints that return [stac::Item] objects return every
/// field of those Items. However, Item objects can have hundreds of fields, or
/// large geometries, and even smaller Item objects can add up when large
/// numbers of them are in results. Frequently, not all fields in an Item are
/// used, so this specification provides a mechanism for clients to request that
/// servers to explicitly include or exclude certain fields.
pub type Item = serde_json::Map<String, serde_json::Value>;

#[cfg(test)]
use {geojson as _, tokio_test as _};
#[cfg(all(not(feature = "client"), test))]
use {mockito as _, tokio as _};

// From https://github.com/rust-lang/cargo/issues/383#issuecomment-720873790,
// may they be forever blessed.
#[cfg(doctest)]
mod readme {
    macro_rules! external_doc_test {
        ($x:expr) => {
            #[doc = $x]
            extern "C" {}
        };
    }

    external_doc_test!(include_str!("../README.md"));
}