Uploaded image for project: 'Node.js Driver'
  1. Node.js Driver
  2. NODE-3059

Document Versioned API Usage in Drivers (with Code Samples)

    • Type: Icon: Task Task
    • Resolution: Fixed
    • Priority: Icon: Major - P3 Major - P3
    • 4.0.0
    • Affects Version/s: None
    • Component/s: None
    • None
    • Needed

      Node team only needs to provide a code snippet to the docs team.
      They will update documentation in DOCSP-14266

      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.

            Assignee:
            eric.adum@mongodb.com Eric Adum (Inactive)
            Reporter:
            backlog-server-pm Backlog - Core Eng Program Management Team
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: