Uploaded image for project: 'C# Driver'
  1. C# Driver
  2. CSHARP-3370

Document Versioned API Usage in Drivers (with Code Samples)

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Closed
    • Priority: Major - P3
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.13.0
    • Component/s: Documentation
    • Security Level: Public
    • Labels:
      None

      Description

      If you think this change is important enough to include a snippet or link on the driver landing pages (e.g. somewhere after "Connect to MongoDB" and "Compatibility" on a page like https://docs.mongodb.com/drivers/swift ), please file a DOCSP ticket and link it to this ticket

      1. Document how to create a client that declares an API Version, include example.
      2. Document the strict option functionality, include example.
      3. Document the deprecation errors option, include example.
      4. Document generic command helper behavior, include example.

      Here's pseudocode Andreas created that can be used for other drivers:

      1. Declare an API version on a client:

      // Declare API version "1" for the client
      serverApi = new ServerApi(v1);
      client = new MongoClient(uri, serverApi);
       
      cursor = client.database.collection.find(...);
      

      2. Strict option:
      Declaring a strict API version will cause the MongoDB server to reject all commands that are not part of the declared API version. This includes command options and aggregation pipeline stages. For example, the following find call would fail because the tailable option is not part of version 1:

      // Declare API version "1" for the client
      serverApi = new ServerApi(v1, strict: true);
      client = new MongoClient(uri, serverApi);
       
      // Fails with an error
      cursor = client.database.collection.find(..., tailable: true);
      

      3. The deprecationErrors option can be used to enable command failures when using functionality that is deprecated from version 1. Note that at the time of this writing, no deprecations in version 1 exist.

      // Declare API version "1" for the client
      serverApi = new ServerApi(v1, deprecationErrors: true);
      client = new MongoClient(uri, serverApi);
      

      4. The declared API version is applied to all commands run through the client, including those sent through the generic command helper. Specifying versioned API options in the command document AND declaring an API version on the client is not supported and will lead to 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.

        Attachments

          Activity

            People

            Assignee:
            mikalai.mazurenka Mikalai Mazurenka
            Reporter:
            backlog-server-pm Backlog - Core Eng Program Management Team
            Participants:
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: