[GODRIVER-1853] Document Versioned API Usage in Drivers (with Code Samples) Created: 29/Jan/21  Updated: 28/Oct/23  Resolved: 11/Feb/21

Status: Closed
Project: Go Driver
Component/s: None
Affects Version/s: None
Fix Version/s: 1.6.0

Type: Task Priority: Minor - P4
Reporter: Backlog - Core Eng Program Management Team Assignee: Benji Rewis (Inactive)
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
Epic Link: Versioned MongoDB API for Drivers

 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.



 Comments   
Comment by Githook User [ 11/Feb/21 ]

Author:

{'name': 'Benjamin Rewis', 'email': '32186188+benjirewis@users.noreply.github.com', 'username': 'benjirewis'}

Message: GODRIVER-1853 Document versioned API usage (#575)
Branch: master
https://github.com/mongodb/mongo-go-driver/commit/305242626f7ca46c8c9d5824a482febc17cc8db4

Comment by Benji Rewis (Inactive) [ 10/Feb/21 ]

https://github.com/mongodb/mongo-go-driver/pull/575

Generated at Thu Feb 08 08:37:16 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.