DOCSP-48859 Add RESTful API tutorial

source/fundamentals/crud.txt

@@ -12,6 +12,8 @@ CRUD Operations
 
    Write </fundamentals/crud/write-operations>
    Read </fundamentals/crud/read-operations>
+   Tutorial: Create a RESTful API </fundamentals/crud/restful-api-tutorial>
 
 - :ref:`csharp-crud-read-operations`
 - :ref:`csharp-crud-write-operations`
+- :ref:`csharp-crud-restful-api-tutorial`

source/fundamentals/crud/restful-api-tutorial.txt

@@ -0,0 +1,384 @@
+.. _csharp-crud-restful-api-tutorial:
+
+=====================================================================
+Tutorial: Create a RESTful API with the {+driver-short+} Driver
+=====================================================================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: crud, code example, tutorial
+   :description: Learn how to use the .NET/C# Driver to create a RESTful API for your application.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Overview
+--------
+
+In this tutorial, you will learn how to create a RESTful API with endpoints that
+perform basic create, read, update, and delete (CRUD) operations across MongoDB
+Atlas.
+
+Prequisites
+-----------
+
+To complete this tutorial, you must have the following:
+
+- An `Atlas account
+  <https://account.mongodb.com/account/register?tck=docs_atlas>`__ with a
+  deployed and configured MongoDB Atlas cluster that is M0 or higher.
+
+- .NET 6.0 or higher `installed <https://dotnet.microsoft.com/en-us/download>`__ on your machine.
+
+To learn how to get started with MongoDB Atlas and how to load sample data, see the
+:atlas:`Get Started with Atlas Guide </getting-started>`. 
+
+This tutorial uses .NET Core 8.0, but you can use any version later than .NET 6.0.
+
+Set Up Your Project
+-------------------
+
+You can create a new .NET Core project using the web application template that
+Microsoft offers. To do this, run the following commands in your terminal:
+
+.. code-block:: bash
+
+   dotnet new webapi -o MongoExample
+   cd MongoExample
+
+To add the {+driver-short+} to your project as a dependency, run the following command:
+
+.. code-block:: bash
+
+   dotnet add package MongoDB.Driver
+
+The preceding commands create a new web application project for .NET core named
+``MongoExample`` and install the latest {+driver-short+}. The template project
+includes some boilerplate files. During this tutorial, you will add to these
+files and remove some of the boilerplate code to create a RESTful API. 
+
+Design a Document Model and Database Service
+--------------------------------------------
+
+In this section, you will create and configure your MongoDB service and define
+the data model for your RESTful API.
+
+.. procedure:: Create a MongoDB Service
+   :style: connected
+
+   .. step:: Create the MongoDBSettings class
+
+      Your MongoDB service will be responisble for establishing a connection and
+      directly working with documents within MongoDB. In your project, create a
+      folder named ``Models``. In the ``Models`` folder, create a new file named
+      ``MongoDBSettings.cs``. In this file, add the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/MongoDBSettingsSetup.cs
+         :language: csharp
+         :dedent:
+
+      The preceding code defines a class named ``MongoDBSettings`` that
+      contains information about your connection, the database name, and the
+      collection name.
+
+   .. step:: Update the appsettings.json file
+
+      The data that will be stored in the class fields defined in the
+      ``MongoDBSettings`` class is found in the projects' ``appsettings.json``
+      file. Open this file and add the following:
+
+      .. code-block:: json
+         :copyable: true
+
+         {
+            "Logging": {
+               "LogLevel": {
+               "Default": "Information",
+               "Microsoft.AspNetCore": "Warning"
+               }
+            },
+         "AllowedHosts": "*",
+         "MongoDB": {
+            "ConnectionURI": "ATLAS_URI_HERE",
+            "DatabaseName": "sample_mflix",
+            "CollectionName": "playlist"
+            }
+         }
+
+      Note the ``MongoDB`` field. This tutorial uses the ``sample_mflix``
+      database and the ``playlist`` collection. Replace the ``ATLAS_URI_HERE``
+      placeholder with your MongoDB Atlas connection string. For more
+      information on how to find your connection string, see the
+      :ref:`csharp-quickstart` guide.
+
+   .. step:: Create the service
+
+      In your project, create a folder named ``Services``. In the ``Services``
+      folder, create a new file named ``MongoDBService.cs`` and add the
+      following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/MongoDBServiceSetup.cs
+         :language: csharp
+         :dedent:
+
+      The preceding code defines a class named ``MongoDBService`` that includes
+      empty asynchronous functions. In this tutorial, you will add code to these
+      functions as you create your endpoints. The passed settings from the
+      ``appsettings.json`` file are set to veriables.
+
+   .. step:: Connect the service to the application
+
+      Open the ``Program.cs`` file and add the following code to the top of the file:
+
+      .. code-block:: csharp
+         :copyable: true
+
+         using MongoExample.Models;
+         using MongoExample.Services;
+
+         var builder = WebApplication.CreateBuilder(args);
+
+         builder.Services.Configure<MongoDBSettings>(builder.Configuration.GetSection("MongoDB"));
+         builder.Services.AddSingleton<MongoDBService>();
+
+      In the preceding code, the ``GetSection`` function pulls your settings
+      from the ``MongoDB`` field in the ``appsettings.json`` file. 
+
+      .. tip::
+
+         If your boilerplate code already has the ``builder`` variable, don't add it twice. 
+
+   .. step:: Create the document model
+
+      Now that the service is set up, you can create a data model for your collection.
+
+      In the ``Models`` folder, create a new file named ``Playlist.cs`` and add
+      the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/PlaylistSetup.cs
+         :language: csharp
+         :dedent:
+
+      In the preceding code, the ``Id`` field is represented as an ``ObjectId``
+      in BSON and the ``_id`` fild within MongoDB. When you work with this
+      locally in your application, it is a string.
+
+      The ``movieIds`` field will be known as ``items``. When sending or
+      receiving JSON, the field will also be known as ``items`` instead of
+      ``movieIds``.
+
+      If you plan to have your local class field match the document field
+      directly, you don't need to define custom mappings. For example, the
+      ``username`` field in the preceding code has no custom mappings. It will
+      be ``username`` in C#, in JSON, and in MongoDB.
+
+You now have a MongoDB service and document model for your collection to work
+with for .NET Core.
+
+Build CRUD Endpoints
+--------------------
+
+To create the CRUD endpoints for this application, you need to update two
+different files within the project. In this section, you can learn how to define
+the endpoint within a controller and update the corresponding work within the
+service.
+
+.. note::
+
+   In this example project, there is no data validation for the HTTP requests.
+
+.. procedure:: Build endpoints to interact with MongoDB
+   :style: connected
+
+   .. step:: Create a controller
+
+      In your project, create a folder named ``Controllers``. In the
+      ``Controllers`` folder, create a new file named ``PlaylistController.cs``
+      and add the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/PlaylistControllerSetup.cs
+         :language: csharp
+         :dedent:
+
+      The ``PlaylistController`` class contains a constructor method that gains
+      access to your singleton service class. Then, there is a series of
+      endpoints for this controller.
+
+   .. step:: Add data through the POST endpoint
+
+      Go to ``Services/MongoDBService.cs`` and update the ``CreateAsync``
+      function to use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/MongoDBServiceComplete.cs
+         :language: csharp
+         :start-after: start-create-async
+         :end-before: end-create-async
+         :dedent:
+
+      The preceding code sets the ``_playlistCollection`` in the constructor
+      method of the service. This lets your application use the
+      ``InsertOneAsync`` method, which takes a passed ``Playlist`` variable and
+      inserts it.
+
+      To complete the creation of the ``POST`` endpoint, go to the
+      ``Controllers/PlaylistController.cs`` file and update the ``Post`` method
+      to use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/PlaylistControllerComplete.cs
+         :language: csharp
+         :start-after: start-post
+         :end-before: end-post
+         :dedent:
+
+      When the ``POST`` endpoint executes, the application takes the
+      ``Playlist`` object from the ``request``, which .NET Core parses, and
+      passes it to the ``CreateAsync`` function in the service. After the
+      insert, the code returns some information about the interaction.
+
+   .. step:: Read data through the GET endpoint
+
+      Go to ``Services/MongoDBService.cs`` and update the ``GetAsync`` function to
+      use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/MongoDBServiceComplete.cs
+         :language: csharp
+         :start-after: start-get-async
+         :end-before: end-get-async
+         :dedent:
+
+      The ``Find`` operation in the preceding code returns all documents that
+      exist in the collection. 
+
+      To complete the creation of the ``GET`` endpoint, go to the
+      ``Controllers/PlaylistController.cs`` file and update the ``Get`` method to
+      use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/PlaylistControllerComplete.cs
+         :language: csharp
+         :start-after: start-get
+         :end-before: end-get
+         :dedent:
+
+   .. step:: Update data using the PUT endpoint
+
+      Go to ``Services/MongoDBService.cs`` and update the ``AddToPlaylistAsync``
+      function to use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/MongoDBServiceComplete.cs
+         :language: csharp
+         :start-after: start-add-to-playlist-async
+         :end-before: end-add-to-playlist-async
+         :dedent:
+
+      The preceding code sets up a match filter to determine which document or
+      documents receive an update, in this case adding an item to your playlist.
+      The code matches based on the ``Id`` field, which is unique. Then, the
+      code defines the update critera, which is an ``AddtoSet`` operation that
+      only adds an item to the array if it doesn't already exist in the array.
+
+      The ``UpdateOneAsync`` methods only updates on document even if the match
+      filter returns more than one match.
+
+      To complete the creation of the PUT endpoint, go to the
+      ``Controllers/PlaylistController.cs`` file and update the
+      ``AddToPlaylist`` function to use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/PlaylistControllerComplete.cs
+         :language: csharp
+         :start-after: start-put
+         :end-before: end-put
+         :dedent:
+
+   .. step:: Delete data using the DELETE endpoint
+
+      Go to ``Services/MongoDBService.cs`` and update the ``DeleteAsync`` function to
+      use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/MongoDBServiceComplete.cs
+         :language: csharp
+         :start-after: start-delete-async
+         :end-before: end-delete-async
+         :dedent:
+
+      The preceding code deletes a single document based on the filter criteria,
+      which matches the unique value of the ``Id`` field.
+
+      To complete the creation of the DELETE endpoint, go to the
+      ``Controllers/PlaylistController.cs`` file and update the
+      ``Delete`` function to use the following code:
+
+      .. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/PlaylistControllerComplete.cs
+         :language: csharp
+         :start-after: start-delete
+         :end-before: end-delete
+         :dedent:
+
+You now have a complete set of CRUD endpoints for your RESTful API.
+
+Test Your API Endpoints
+-----------------------
+
+With the endpoints created, you can test them using the Swagger UI that is
+built-in to the boilerplate .NET Core application. To do this, go to
+``Program.cs`` file and remove any code from the template project related to
+``WeatherForecast`` and similar. Update the file to include the following code:
+
+.. literalinclude:: /includes/fundamentals/code-examples/restful-api-tutorial/MongoDBExampleProgram.cs
+   :language: csharp
+   :dedent:
+   :start-after: start-program-example
+   :end-before: end-program-example
+
+You can replace any repetitive code in the boilerplate with the preceding code.
+
+Execute the following command to run your application:
+
+.. code-block:: bash
+
+   dotnet run
+
+After the application starts, open your browser and go to your configured
+localhost URL to access the Swagger UI, for example
+``http://localhost:5000/swagger``. The Swagger UI looks like the following:
+
+.. figure:: /includes/figures/restful-api-tutorial-swagger-ui.jpg
+   :alt: Swagger UI
+   :align: center
+
+   The Swagger UI for the RESTful API.
+
+You can test the application by clicking the ``Try it out`` button on each
+endpoint. To get started, go to the ``/api/playlists`` ``POST`` endpoint
+to add some data to the database. Add the following as dummy data:
+
+.. code-block:: json
+   :copyable: true
+
+   {
+      "username": "testuser",
+      "items": [
+         "1234",
+         "5678"
+      ]
+   }
+
+Run this request to insert data into the database. You can then go to the ``GET``
+endpoint to see the data you just inserted. You can also test the ``PUT`` and
+``DELETE`` endpoints to update and delete data.
+
+Next Steps
+----------
+
+To learn more about the operations discussed in this tutorial, see the following
+guides:
+
+- :ref:`csharp-insert-guide`
+- :ref:`csharp-retrieve`
+- :ref:`csharp-update-one`
+- :ref:`csharp-delete-guide`