DOCSP-28246 stable api updates (#857)

* DOCSP-28246: Stable API updates

Author: Chris Cho

source/c.txt

@@ -38,75 +38,37 @@ Installation
 See `Installing the MongoDB C Driver (libmongoc) and BSON library (libbson)
 <https://mongoc.org/libmongoc/current/installing.html>`__.
 
-
 .. _connect-atlas-c-driver:
 
 Connect to MongoDB Atlas
 ------------------------
 
-.. include:: /includes/atlas-connect-blurb.rst
-
-.. code-block:: c
-
-   #include <mongoc/mongoc.h>
-
-   int
-   main (int argc, char *argv[])
-   {
-      mongoc_database_t *database;
-      mongoc_client_t *client;
-
-      mongoc_init ();
-
-      // Replace the uri string with your MongoDB deployment's connection string.
-      client = mongoc_client_new(
-         "mongodb+srv://<username>:<password>@<cluster-url>/test?retryWrites=true&w=majority"
-      );
-      database = mongoc_client_get_database (client, "test");
-
-      mongoc_database_destroy (database);
-      mongoc_client_destroy (client);
-
-      mongoc_cleanup ();
-
-      return 0;
-   }
-
-.. include:: /includes/serverless-compatibility.rst
+You can use the following connection snippet to test your connection to your
+MongoDB deployment on Atlas:
 
-See `Advanced Connections <https://mongoc.org/libmongoc/current/advanced-connections.html>`__
-for more ways to connect.
+.. literalinclude:: /includes/connection-snippets/scram/c-connection.c
+   :language: c
 
-{+stable-api+}
---------------
+This connection snippet uses the {+stable-api+} feature which you can use when
+connecting to MongoDB Server v5.0 and later and the C driver v1.18 and later.
 
-You can use the {+stable-api+} feature starting with MongoDB Server version
-5.0 and C Driver version 1.18. When you use the {+stable-api+} feature,
-you can update your driver or server without worrying about backward
-compatibility issues with any commands covered by the {+stable-api+}.
+When you use this feature, you can update your driver or server without 
+worrying about backward compatibility issues with any commands covered by the
+{+stable-api+}.
 
 .. include:: /includes/stable-api-notice.rst
 
-To use this feature, construct a MongoDB client instance, specifying a version
-of the {+stable-api+}:
-
-.. code-block:: c
-
-   // Replace <connection string> with your MongoDB deployment's connection string.
-   const char *uri_string = "<connection string>";
-   mongoc_uri_t *uri;
-   mongoc_client_t *client;
-   mongoc_server_api_t *api;
-   bson_error_t error;
+.. _connect-atlas-no-stable-api-c-driver:
 
-   mongoc_init ();
+Connect to MongoDB Atlas Without the Stable API
+-----------------------------------------------
 
-   uri = mongoc_uri_new_with_error (uri_string, &error);
-   client = mongoc_client_new_from_uri (uri);
+If you are using a version of MongoDB or the driver that lacks support for the
+{+stable-api+}, you can use the following code snippet to test your connection
+to your MongoDB deployment on Atlas:
 
-   // Set the version of the {+stable-api+} on the client.
-   api = mongoc_server_api_new (MONGOC_SERVER_API_V1);
-   mongoc_client_set_server_api (client, api, &error);
+.. literalinclude:: /includes/connection-snippets/scram/c-connection-no-stable-api.c
+   :language: c
 
 Connect to a MongoDB Server on Your Local Machine
 -------------------------------------------------
@@ -117,6 +79,11 @@ To test whether you can connect to your server, replace the connection
 string in the :ref:`Connect to MongoDB Atlas <connect-atlas-c-driver>` code
 example and run it.
 
+See `Advanced Connections <https://mongoc.org/libmongoc/current/advanced-connections.html>`__
+for more ways to connect.
+
+.. include:: /includes/serverless-compatibility.rst
+
 Compatibility
 -------------
 

source/cxx.txt

@@ -42,24 +42,32 @@ See `Installing the mongocxx driver <https://mongocxx.org/mongocxx-v3/installati
 Connect to MongoDB Atlas
 ------------------------
 
-.. include:: /includes/atlas-connect-blurb.rst
+You can use the following connection snippet to test your connection to your
+MongoDB deployment on Atlas:
 
-.. code-block:: cpp
+.. literalinclude:: /includes/connection-snippets/scram/cxx-connection.cpp
+   :language: cpp
 
-   #include <mongocxx/client.hpp>
-   #include <mongocxx/instance.hpp>
+This connection snippet uses the {+stable-api+} feature which you can use when
+connecting to MongoDB Server v5.0 and later and the C++ driver v3.7 and later.
 
-   //...
+When you use this feature, you can update your driver or server without 
+worrying about backward compatibility issues with any commands covered by the
+{+stable-api+}.
 
-   mongocxx::instance inst{}; // This should be done only once.
-   mongocxx::client conn{
-      mongocxx::uri{
-         "mongodb+srv://<username>:<password>@<cluster-url>/test?retryWrites=true&w=majority"
-      }
-   };
-   mongocxx::database db = conn["test"];
+.. include:: /includes/stable-api-notice.rst
 
-.. include:: /includes/serverless-compatibility.rst
+.. _connect-atlas-no-stable-api-cxx-driver:
+
+Connect to MongoDB Atlas Without the Stable API
+-----------------------------------------------
+
+If you are using a version of MongoDB or the driver that lacks support for the
+{+stable-api+}, you can use the following code snippet to test your connection
+to your MongoDB deployment on Atlas:
+
+.. literalinclude:: /includes/connection-snippets/scram/cxx-connection-no-stable-api.cpp
+   :language: cpp 
 
 Connect to a MongoDB Server on Your Local Machine
 -------------------------------------------------

source/includes/connection-snippets/scram/c-connection-no-stable-api.c

@@ -0,0 +1,42 @@
+#include <mongoc/mongoc.h>
+
+int main (int argc, char **argv)
+{
+	mongoc_client_t *client = NULL;
+	bson_error_t error = {0};
+	mongoc_database_t *database = NULL;
+	bson_t *command = NULL, reply;
+
+
+	// Initialize the MongoDB C Driver.
+	mongoc_init ();
+
+	// Replace the <connection string> with your MongoDB deployment's connection string.
+	client = mongoc_client_new("<connection string>");
+
+	// Get a handle on the "admin" database.
+	database = mongoc_client_get_database (client, "admin");
+  
+	// Ping the database.
+	command = BCON_NEW("ping", BCON_INT32(1));
+	if (mongoc_database_command_simple(database, command, NULL, &reply, &error))
+	{
+		printf("Pinged your deployment. You successfully connected to MongoDB!\n");
+	}
+	else
+	{
+		// Error condition.
+		printf("Error: %s\n", error.message);
+		return 0;
+	}
+  
+
+	// Perform Cleanup.
+	bson_destroy (&reply);
+	bson_destroy (command);
+	mongoc_database_destroy (database);
+	mongoc_client_destroy (client);
+	mongoc_cleanup ();
+
+	return 0;
+}

source/includes/connection-snippets/scram/c-connection.c

@@ -0,0 +1,51 @@
+#include <mongoc/mongoc.h>
+
+int main (int argc, char **argv)
+{
+  mongoc_client_t *client = NULL;
+  bson_error_t error = {0};
+  mongoc_server_api_t *api = NULL;
+  mongoc_database_t *database = NULL;
+  bson_t *command = NULL, reply;
+
+  // Initialize the MongoDB C Driver.
+  mongoc_init ();
+
+  // Replace the <connection string> with your MongoDB deployment's connection string.
+  client = mongoc_client_new("<connection string>");
+
+  // Set the version of the Stable API on the client.
+  api = mongoc_server_api_new (MONGOC_SERVER_API_V1);
+  if (!mongoc_client_set_server_api (client, api, &error))
+  {
+	  // Error condition.
+	  printf("Error: %s\n", error.message);
+	  return 0;
+  }
+
+  // Get a handle on the "admin" database.
+  database = mongoc_client_get_database (client, "admin");
+  
+  // Ping the database.
+  command = BCON_NEW("ping", BCON_INT32(1));
+  if (mongoc_database_command_simple(database, command, NULL, &reply, &error))
+  {
+    printf("Pinged your deployment. You successfully connected to MongoDB!\n");
+  }
+  else
+  {
+    // Error condition.
+    printf("Error: %s\n", error.message);
+    return 0;
+  }
+  
+
+  // Perform Cleanup.
+  bson_destroy (&reply);
+  bson_destroy (command);
+  mongoc_database_destroy (database);
+  mongoc_client_destroy (client);
+  mongoc_cleanup ();
+
+  return 0;
+}

source/includes/connection-snippets/scram/cxx-connection-no-stable-api.cpp

@@ -0,0 +1,31 @@
+#include <bsoncxx/json.hpp>
+#include <mongocxx/client.hpp>
+#include <mongocxx/instance.hpp>
+
+int main()
+{ 
+  try
+  {
+    // Create an instance.
+    mongocxx::instance inst{};
+  
+    // Replace the connection string with your MongoDB deployment's connection string.
+    const auto uri = mongocxx::uri{"<connection string>"};
+  
+    // Setup the connection and get a handle on the "admin" database.
+    mongocxx::client conn{ uri };
+    mongocxx::database db = conn["admin"];
+    
+    // Ping the database.
+    const auto ping_cmd = bsoncxx::builder::basic::make_document(bsoncxx::builder::basic::kvp("ping", 1));
+    db.run_command(ping_cmd.view());
+    std::cout << "Pinged your deployment. You successfully connected to MongoDB!" << std::endl;   
+  }
+  catch (const std::exception& e) 
+  {
+    // Handle errors.
+    std::cout<< "Exception: " << e.what() << std::endl;
+  }
+
+  return 0;
+}

source/includes/connection-snippets/scram/cxx-connection.cpp

@@ -0,0 +1,36 @@
+#include <bsoncxx/json.hpp>
+#include <mongocxx/client.hpp>
+#include <mongocxx/instance.hpp>
+
+int main()
+{ 
+  try
+  {
+    // Create an instance.
+    mongocxx::instance inst{};
+  
+    // Replace the connection string with your MongoDB deployment's connection string.
+    const auto uri = mongocxx::uri{"<connection string>"};
+  
+    // Set the version of the Stable API on the client.
+    mongocxx::options::client client_options;
+    const auto api = mongocxx::options::server_api{ mongocxx::options::server_api::version::k_version_1 };
+    client_options.server_api_opts(api);
+  
+    // Setup the connection and get a handle on the "admin" database.
+    mongocxx::client conn{ uri, client_options };
+    mongocxx::database db = conn["admin"];
+    
+    // Ping the database.
+    const auto ping_cmd = bsoncxx::builder::basic::make_document(bsoncxx::builder::basic::kvp("ping", 1));
+    db.run_command(ping_cmd.view());
+    std::cout << "Pinged your deployment. You successfully connected to MongoDB!" << std::endl;
+  }
+  catch (const std::exception& e) 
+  {
+    // Handle errors.
+    std::cout<< "Exception: " << e.what() << std::endl;
+  }
+
+  return 0;
+}