Skip to content

Commit

Permalink
RUST-1173 Replace "Versioned API" references with "Stable API" (#585)
Browse files Browse the repository at this point in the history
  • Loading branch information
@isabelatkinson
isabelatkinson authored Mar 1, 2022
1 parent 8e07cf4 commit ae4ae58
Show file tree
Hide file tree
Showing 2 changed files with 28 additions and 28 deletions.
10 changes: 5 additions & 5 deletions src/client/options/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -322,8 +322,8 @@ impl<'de> Deserialize<'de> for ServerApiVersion {
}
}

/// Options used to declare a versioned server API. For more information, see the [Versioned API](
/// https://docs.mongodb.com/v5.0/reference/versioned-api/) manual page.
/// Options used to declare a stable server API. For more information, see the [Stable API](
/// https://docs.mongodb.com/v5.0/reference/stable-api/) manual page.
#[serde_with::skip_serializing_none]
#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, TypedBuilder)]
#[builder(field_defaults(setter(into)))]
Expand Down Expand Up @@ -506,13 +506,13 @@ pub struct ClientOptions {
/// The declared API version is applied to all commands run through the client, including those
/// sent through any handle derived from the client.
///
/// Specifying versioned API options in the command document passed to `run_command` AND
/// Specifying stable API options in the command document passed to `run_command` AND
/// declaring an API version on the client is not supported and is considered undefined
/// behaviour. To run any command with a different API version or without declaring one, create
/// a separate client that declares the appropriate API version.
///
/// For more information, see the [Versioned API](
/// https://docs.mongodb.com/v5.0/reference/versioned-api/) manual page.
/// For more information, see the [Stable API](
/// https://docs.mongodb.com/v5.0/reference/stable-api/) manual page.
#[builder(default)]
pub server_api: Option<ServerApi>,

Expand Down
46 changes: 23 additions & 23 deletions src/test/documentation_examples/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1373,61 +1373,61 @@ type GenericResult<T> = std::result::Result<T, Box<dyn std::error::Error>>;

#[allow(unused_variables)]
#[cfg(not(feature = "sync"))]
async fn versioned_api_examples() -> GenericResult<()> {
async fn stable_api_examples() -> GenericResult<()> {
let setup_client = TestClient::new().await;
if setup_client.server_version_lt(4, 9) {
log_uncaptured("skipping versioned API examples due to unsupported server version");
log_uncaptured("skipping stable API examples due to unsupported server version");
return Ok(());
}
if setup_client.is_sharded() && setup_client.server_version <= Version::new(5, 0, 2) {
// See SERVER-58794.
log_uncaptured(
"skipping versioned API examples due to unsupported server version on sharded topology",
"skipping stable API examples due to unsupported server version on sharded topology",
);
return Ok(());
}
if setup_client.is_load_balanced() {
log_uncaptured("skipping versioned API examples due to load-balanced topology");
log_uncaptured("skipping stable API examples due to load-balanced topology");
return Ok(());
}

let uri = DEFAULT_URI.clone();
// Start Versioned API Example 1
// Start Stable API Example 1
let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder().version(ServerApiVersion::V1).build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;
// End Versioned API Example 1
// End Stable API Example 1

// Start Versioned API Example 2
// Start Stable API Example 2
let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
.version(ServerApiVersion::V1)
.strict(true)
.build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;
// End Versioned API Example 2
// End Stable API Example 2

// Start Versioned API Example 3
// Start Stable API Example 3
let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
.version(ServerApiVersion::V1)
.strict(false)
.build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;
// End Versioned API Example 3
// End Stable API Example 3

// Start Versioned API Example 4
// Start Stable API Example 4
let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
.version(ServerApiVersion::V1)
.deprecation_errors(true)
.build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;
// End Versioned API Example 4
// End Stable API Example 4

let mut options = ClientOptions::parse(&uri).await?;
let server_api = ServerApi::builder()
Expand All @@ -1436,12 +1436,12 @@ async fn versioned_api_examples() -> GenericResult<()> {
.build();
options.server_api = Some(server_api);
let client = Client::with_options(options)?;
let db = client.database("versioned-api-migration-examples");
let db = client.database("stable-api-migration-examples");
db.collection::<Document>("sales").drop(None).await?;

use std::{error::Error, result::Result};

// Start Versioned API Example 5
// Start Stable API Example 5
// With the `bson-chrono-0_4` feature enabled, this function can be dropped in favor of using
// `chrono::DateTime` values directly.
fn iso_date(text: &str) -> Result<bson::DateTime, Box<dyn Error>> {
Expand All @@ -1458,9 +1458,9 @@ async fn versioned_api_examples() -> GenericResult<()> {
doc! { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : iso_date("2021-02-15T14:12:12Z")? },
doc! { "_id" : 8, "item" : "abc", "price" : 10, "quantity" : 5, "date" : iso_date("2021-03-16T20:20:13Z")? }
], None).await?;
// End Versioned API Example 5
// End Stable API Example 5

// Start Versioned API Example 6
// Start Stable API Example 6
let result = db
.run_command(
doc! {
Expand All @@ -1476,28 +1476,28 @@ async fn versioned_api_examples() -> GenericResult<()> {
// CommandError {
// code: 323,
// code_name: "APIStrictError",
// message: "Provided apiStrict:true, but the command count is not in API Version 1. Information on supported commands and migrations in API Version 1 can be found at https://dochub.mongodb.org/core/manual-versioned-api",
// message: "Provided apiStrict:true, but the command count is not in API Version 1. Information on supported commands and migrations in API Version 1 can be found at https://docs.mongodb.com/v5.0/reference/stable-api/",
// },
// )
}
// End Versioned API Example 6
// End Stable API Example 6
if let ErrorKind::Command(ref err) = *result.as_ref().unwrap_err().kind {
assert_eq!(err.code, 323);
assert_eq!(err.code_name, "APIStrictError".to_string());
} else {
panic!("invalid result {:?}", result);
};

// Start Versioned API Example 7
// Start Stable API Example 7
let count = db
.collection::<Document>("sales")
.count_documents(None, None)
.await?;
// End Versioned API Example 7
// End Stable API Example 7

// Start Versioned API Example 8
// Start Stable API Example 8
assert_eq!(count, 8);
// End Versioned API Example 8
// End Stable API Example 8

Ok(())
}
Expand Down Expand Up @@ -1850,7 +1850,7 @@ async fn test() {
projection_examples(&coll).await.unwrap();
update_examples(&coll).await.unwrap();
delete_examples(&coll).await.unwrap();
versioned_api_examples().await.unwrap();
stable_api_examples().await.unwrap();
aggregation_examples().await.unwrap();
run_command_examples().await.unwrap();
index_examples().await.unwrap();
Expand Down

0 comments on commit ae4ae58

Please sign in to comment.