docs.mongodb.com Open in urlscan Pro
151.101.130.133 Public Scan

Back to summary

Submitted URL:
https://s413370795.t.en25.com/e/er?utm_campaign=Int_EM_Mongodb%204.0%20Eol%20Not-Atlas%20Cust_01_22_WW&utm_medium=email&utm_so...
Effective URL:
https://docs.mongodb.com/manual/reference/stable-api/
Submission: On February 02 via api (February 2nd 2022, 3:38:49 am UTC) from SG — Scanned from DE

Form analysis
2 forms found in the DOM

GET https://docs.mongodb.com/search

<form role="search" method="GET" action="https://docs.mongodb.com/search" class="css-dc0gsv">
  <div class="css-87svlz">
    <div class="css-36i4c2"><input type="text" placeholder="Search all documentation..." class="css-etrcff" value=""></div>
    <div class="css-v2nqhr">
      <div class="css-aef77t"><button role="label" type="button" class="css-14k7wrz"><span data-testid="selected-value" class="css-6k4l2y">All Documentation</span>
          <div class="css-109dpaz"><svg data-testid="icon" width="16" height="9" viewBox="0 0 16 9" fill="none" xmlns="http://www.w3.org/2000/svg" class="css-1yzkxhp">
              <path d="M1.06689 0.799988L8.00023 7.73332L14.9336 0.799988" stroke-linecap="round" stroke-linejoin="round" class="css-1tlq8q9"></path>
            </svg></div>
        </button>
        <div class="css-hn9qqo">
          <ul data-testid="options" role="listbox" class="css-ac9zo2">
            <li role="option" tabindex="0" class="css-11dtrvq">General Information</li>
            <li role="option" tabindex="0" class="css-11dtrvq">All Documentation</li>
            <li role="option" tabindex="0" class="css-11dtrvq">Realm Documentation</li>
            <li role="option" tabindex="0" class="css-11dtrvq">Developer Articles &amp; Topics</li>
            <li role="option" tabindex="0" class="css-11dtrvq">Community Forums</li>
            <li role="option" tabindex="0" class="css-11dtrvq">Blog</li>
          </ul>
        </div>
      </div><input type="hidden" id="q" name="q" value="">
      <div class="css-1myrko"><button tabindex="0" class=" css-1cd5y1y" data-track="true"><img alt="search icon" src="https://webimages.mongodb.com/_com_assets/cms/krc3hljsdwdfd2w5d-web-actions-search.svg?auto=format%252Ccompress"
            class="css-r9fohf"></button></div>
    </div>
  </div>
</form>

GET https://docs.mongodb.com/search

<form role="search" method="GET" action="https://docs.mongodb.com/search" class="css-11a71ad">
  <div class="css-7590ag"><input type="text" placeholder="Search all documentation..." class="css-xrkki1" value=""></div>
  <div class="css-abpu8v"><select class="select-overlay css-15v6p12" id="filter-select">
      <option value="General Information">General Information</option>
      <option selected="" value="All Documentation">All Documentation</option>
      <option value="Realm Documentation">Realm Documentation</option>
      <option value="Developer Articles &amp; Topics">Developer Articles &amp; Topics</option>
      <option value="Community Forums">Community Forums</option>
      <option value="Blog">Blog</option>
    </select><input type="hidden" id="q" name="q" value="">
    <div class="css-1myrko"><button tabindex="0" class="css-1dvvi57" data-track="true">Search</button></div>
  </div>
</form>

Text Content

All Documentation

* General Information
* All Documentation
* Realm Documentation
* Developer Articles & Topics
* Community Forums
* Blog

* Products
* Solutions
* Resources
* Company
* Pricing

General InformationAll DocumentationRealm DocumentationDeveloper Articles &
TopicsCommunity ForumsBlog
Search
Docs Menu

MongoDB Documentation

--------------------------------------------------------------------------------

Back to Develop Applications
* MongoDB Manual
Version 5.0
* Introduction
* Installation
* MongoDB Shell (mongosh)
* MongoDB CRUD Operations
* Aggregation
* Data Models
* Transactions
* Indexes
* Security
* Change Streams
* Replication
* Sharding
* Administration
* Storage
* Frequently Asked Questions
* Reference
* Operators
* Database Commands
* mongosh Methods
* Legacy mongo Shell
* MongoDB Package Components
* Configuration File Options
* MongoDB Server Parameters
* MongoDB Limits and Thresholds
* Explain Results
* System Collections
* Connection String URI Format
* Collation
* MongoDB Wire Protocol
* Log Messages
* Exit Codes and Statuses
* Glossary
* Default MongoDB Port
* Default MongoDB Read Concerns/Write Concerns
* Server Sessions
* Stable API
* Migrate to a Later API Version
* Release Notes
* Technical Support

Docs Home → Develop Applications → MongoDB Manual

STABLE API

On this page

* What is the Stable API, and Should You Use It?
* Backward Compatibility Guarantee
* Declare the API Version
* Create a Strict Client
* Migrate To Stable API Commands
* How To Use Commands and Features Outside of the Stable API
* API V1 Commands
* Parameters
* Behavior

WHAT IS THE STABLE API, AND SHOULD YOU USE IT?

The MongoDB Stable API (previously labeled the Versioned API) lets you upgrade
your MongoDB server at will, and ensure that behavior changes between MongoDB
versions do not break your application.

MongoDB 5.0 introduces the Stable API for applications communicating with
MongoDB server products. The Stable API allows you to specify which version of
the MongoDB API your application runs against.

The Stable API provides long-term API stability for applications and supports
more frequent releases and automatic server upgrades. This allows your
applications to take advantage of rapidly released features without risking
backwards-breaking changes.

The default behavior for your driver connection will continue to function as
expected, even if you do not explicitly specify an apiVersion.

The Stable API encompasses the subset of MongoDB commands that applications use
to read and write data, create collections and indexes, and perform other common
tasks.

Note

Starting in Feburary 2022, the "Versioned API" terminology was changed to
"Stable API". All concepts and features remain the same with this naming change.

BACKWARD COMPATIBILITY GUARANTEE

Your application will not experience significant behavior changes resulting from
server upgrades. This guarantee holds as long as the new server supports your
specified API version.

To guarantee backward compatibility, your application must:

* Declare an API version
* Only use commands and features supported in your specified API version
* Deploy with a supported version of an official driver

DECLARE THE API VERSION

--------------------------------------------------------------------------------

➤ Use the Select your language drop-down menu in the upper-right to set the
language of the examples on this page.

--------------------------------------------------------------------------------

To use the Stable API, upgrade to the latest driver and create your
application's MongoClient:

MongoDB ShellCC#GoJava (Sync)Node.jsPHPPython

mongosh --apiVersion 1

MongoDB Shell

"1" is currently the only API version available.

By default, clients are non-strict. A non-strict client allows you to run any
command, regardless of whether or not it belongs to the Stable API.

CREATE A STRICT CLIENT

A strict client rejects all commands outside of the Stable API. Attempts to use
commands outside of the Stable API will receive the APIVersionError response.

Use the sample code to create a strict client:

MongoDB ShellCC#GoJava (Sync)Node.jsPHPPython

mongosh --apiVersion 1 --apiStrict

MongoDB Shell

MIGRATE TO STABLE API COMMANDS

To migrate your application to use the Stable API, you must:

1. Run your application's test suite with the new MongoClient options.
2. Determine which commands and features you're using that are outside of the
Stable API.
3. Migrate to alternative commands and features in the Stable API.

Once your application uses only commands and features defined in the Stable API,
you can redeploy it with the new MongoClient options and be confident that
future server upgrades won't negatively impact your application.

EXAMPLE: COUNT MIGRATION

This example shows how to migrate an application that implements the count
command to an alternative method of counting documents. Since the count command
does not belong to the Stable API, this application cannot use the Stable API
until the count command is removed from the code.

Use the sample code to create a sales collection in mongosh:

db.sales.insertMany([ { "_id" : 1, "item" : "abc", "price" : 10, "quantity" : 2, "date" : ISODate("2021-01-01T08:00:00Z") }, { "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "date" : ISODate("2021-02-03T09:00:00Z") }, { "_id" : 3, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-03T09:05:00Z") }, { "_id" : 4, "item" : "abc", "price" : 10, "quantity" : 10, "date" : ISODate("2021-02-15T08:00:00Z") }, { "_id" : 5, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T09:05:00Z") }, { "_id" : 6, "item" : "xyz", "price" : 5, "quantity" : 5, "date" : ISODate("2021-02-15T12:05:10Z") }, { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2021-02-15T14:12:12Z") }, { "_id" : 8, "item" : "abc", "price" : 10, "quantity" : 5, "date" : ISODate("2021-03-16T20:20:13Z") }])

STABLE API ERROR RESPONSE

For example, issuing db.sales.count() results in this error:

{ "ok" : 0, "errmsg" : "Provided apiStrict:true, but the command count is not in API Version 1", "code" : 323, "codeName" : "APIStrictError"}

However, the aggregate command is in the Stable API and can be used to obtain a
count. Use the sample code to obtain a count from the sales collection in
mongosh:

db.sales.aggregate([ { $group: { _id: null, count: { $count: { } } } }])

This results in a document where the count field contains the number of
documents in the collection:

{ "_id" : null, "count" : 8 }

HOW TO USE COMMANDS AND FEATURES OUTSIDE OF THE STABLE API

To use commands and features outside of the Stable API, you can connect to your
deployment with a non-strict client. By default, clients are non-strict.

Use the sample code to create a non-strict client:

MongoDB ShellCC#GoJava (Sync)Node.jsPHPPython

mongosh --apiVersion 1

MongoDB Shell

Using this non-strict client allows you to run commands outside of the Stable
API. For example, this non-strict client now allows you to use the count command
once again.

Important

Commands and features outside of the Stable API do not have the same backward
compatibility guarantees as versioned alternatives.

API V1 COMMANDS

API V1 protects you from API-breaking changes for the following commands:

* abortTransaction
* aggregate (with limitations) [1]
* authenticate
* collMod
* commitTransaction
* create (with limitations) [1]
* createIndexes (with limitations) [1]
* delete
* drop
* dropDatabase
* dropIndexes
* endSessions
* explain (with limitations) [2]
* find (with limitations) [1]
* findAndModify
* getMore
* insert
* hello
* killCursors
* listCollections
* listDatabases
* listIndexes
* ping
* refreshSessions
* update

[1](1, 2, 3, 4) API V1 may not support all available options for these commands.
Refer to the specific command documentation for limitations specific to API V1.

[2] MongoDB does not guarantee that the output of the explain command will
conform to the same format in future API versions.

PARAMETERS

You can specify the following optional parameters for Stable API in your
application's MongoDB driver connection code. Check the MongoDB driver
documentation for the driver you use in your application for more information:

Parameter
Type
Description
apiVersion
string

API Version. "1" is currently the only supported API Version.

See APIVersionError.

apiStrict
boolean

If true, your application can only use commands defined for your specified
apiVersion.

If not specified, defaults to false.

See APIStrictError.

apiDeprecationErrors
boolean

If true, your application errors if it invokes a command or behavior that is
deprecated in the specified apiVersion.

If not specified, defaults to false.

See APIDeprecationError.

BEHAVIOR

PARAMETER VALIDATION

Starting in MongoDB 5.0, API V1 database commands raise an error if passed a
parameter not explicitly accepted by the command.

In MongoDB 4.4 and earlier, unrecognized parameters are silently ignored.

API ERROR RESPONSES

This table shows error responses for problematic Stable API requests.

Server Response
Request
APIDeprecationError

Specifies { apiDeprecationErrors: true } with API version V and uses a behavior
deprecated in V.

APIStrictError

Specifies { apiStrict: true } with API version V, but uses a behavior not in
version V.

APIVersionError

Specifies an apiVersion that the server does not support.

InvalidOptions

Specifies { apiStrict: true } or { apiDeprecationErrors: true } but omits
apiVersion.

← Server SessionsMigrate to a Later API Version →

Select your language

MongoDB Shell

On this page

About

* Careers
* Investor Relations
* Legal Notices
* Privacy Notices
* Security Information
* Trust Center

Support

* Contact Us
* Customer Portal
* Atlas Status
* Paid Support

Social

* Github
* Stack Overflow
* LinkedIn
* Youtube
* Twitter
* Twitch
* Facebook

PRIVACY PREFERENCE CENTER

"Cookies" are small files that enable us to store information while you visit
one of our websites. When you visit any website, it may store or retrieve
information on your browser, mostly in the form of cookies. This information
might be about you, your preferences or your device and is mostly used to make
the site work as you expect it to. The information does not usually directly
identify you, but it can give you a more personalized web experience. Because we
respect your right to privacy, you can choose not to allow some types of
cookies, but essential cookies are always enabled. Click on the different
category headings to find out more and change our default settings. However,
blocking some types of cookies may impact your experience of the site and the
services we are able to offer.
MongoDB Privacy Policy
Allow All

MANAGE CONSENT PREFERENCES

STRICTLY NECESSARY COOKIES

Always Active

These cookies are necessary for the website to function and cannot be switched
off in our systems. They are usually only set in response to actions made by you
which amount to a request for services, such as setting your privacy
preferences, logging in or filling in forms. You can set your browser to block
or alert you about these cookies, but some parts of the site will not then work.
These cookies do not store any personally identifiable information.

PERFORMANCE COOKIES

Performance Cookies

These cookies allow us to count visits and traffic sources so we can measure and
improve the performance of our site. They help us to know which pages are the
most and least popular and see how visitors move around the site. All
information these cookies collect is aggregated and therefore anonymous. If you
do not allow these cookies we will not know when you have visited our site, and
will not be able to monitor its performance.

FUNCTIONAL COOKIES

Functional Cookies

These cookies enable the website to provide enhanced functionality and
personalisation. They may be set by us or by third party providers whose
services we have added to our pages. If you do not allow these cookies then some
or all of these services may not function properly.

TARGETING COOKIES

Targeting Cookies

These cookies may be set through our site by our advertising partners. They may
be used by those companies to build a profile of your interests and show you
relevant adverts on other sites. They do not store directly personal
information, but are based on uniquely identifying your browser and internet
device. If you do not allow these cookies, you will experience less targeted
advertising.

SOCIAL MEDIA COOKIES

Social Media Cookies

These cookies are set by a range of social media services that we have added to
the site to enable you to share our content with your friends and networks. They
are capable of tracking your browser across other sites and building up a
profile of your interests. This may impact the content and messages you see on
other websites you visit. If you do not allow these cookies you may not be able
to use or see these sharing tools.

BACK BUTTON PERFORMANCE COOKIES

Vendor Search Search Icon
Filter Icon

Clear
checkbox label label
Apply Cancel
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label

Confirm My Choices

By clicking "Accept All Cookies", you agree to the storing of cookies on your
device to enhance site navigation, analyze site usage, and assist in our
marketing efforts. You can enable and disable optional cookies as desired. Read
our Privacy Policy. Read our Privacy Policy

Manage Cookies Accept All Cookies

docs.mongodb.com Open in urlscan Pro 151.101.130.133 Public Scan

Form analysis 2 forms found in the DOM

GET https://docs.mongodb.com/search

GET https://docs.mongodb.com/search

Text Content

docs.mongodb.com Open in urlscan Pro
151.101.130.133 Public Scan

Form analysis
2 forms found in the DOM