# `server_api` – Support for MongoDB Stable API

Support for MongoDB Stable API.

## MongoDB Stable API

Starting in MongoDB 5.0, applications can specify the server API version to use when creating a `MongoClient`. Doing so ensures that the driver behaves in a manner compatible with that server API version, regardless of the server’s actual release version.

### Declaring an API Version

Attention

Stable API requires MongoDB >=5.0.

To configure MongoDB Stable API, pass the `server_api` keyword option to `MongoClient`:

    >>> from pymongo.mongo_client import MongoClient
    >>> from pymongo.server_api import ServerApi
    >>>
    >>> # Declare API version "1" for MongoClient "client"
    >>> server_api = ServerApi('1')
    >>> client = MongoClient(server_api=server_api)

The declared API version is applied to all commands run through `client`, including those sent through the generic `command()` helper.

Note

Declaring an API version on the `MongoClient` and specifying stable API options in `command()` command document is not supported and will lead to undefined behaviour.

To run any command without declaring a server API version or using a different API version, create a separate `MongoClient` instance.

### Strict Mode

Configuring `strict` mode will cause the MongoDB server to reject all commands that are not part of the declared `ServerApi.version`. This includes command options and aggregation pipeline stages.

For example:

    >>> server_api = ServerApi('1', strict=True)
    >>> client = MongoClient(server_api=server_api)
    >>> client.test.command('count', 'test')
    Traceback (most recent call last):
    ...
    pymongo.errors.OperationFailure: Provided apiStrict:true, but the command count is not in API Version 1, full error: {'ok': 0.0, 'errmsg': 'Provided apiStrict:true, but the command count is not in API Version 1', 'code': 323, 'codeName': 'APIStrictError'

### Detecting API Deprecations

The `deprecationErrors` option can be used to enable command failures when using functionality that is deprecated from the configured `ServerApi.version`. For example:

    >>> server_api = ServerApi('1', deprecation_errors=True)
    >>> client = MongoClient(server_api=server_api)

Note that at the time of this writing, no deprecated APIs exist.

## Classes

class pymongo.server_api.ServerApi(version, strict=None, deprecation_errors=None)

  Options to configure MongoDB Stable API.

  Parameters:

    - version (str) – The API version string. Must be one of the values in `ServerApiVersion`.

    - strict (Optional[bool]) – Set to `True` to enable API strict mode. Defaults to `None` which means “use the server’s default”.

    - deprecation_errors (Optional[bool]) – Set to `True` to enable deprecation errors. Defaults to `None` which means “use the server’s default”.

  Added in version 3.12.

  property deprecation_errors: bool | None

    The API deprecation errors setting.

    When set, this value is sent to the server in the “apiDeprecationErrors” field.

  property strict: bool | None

    The API strict mode setting.

    When set, this value is sent to the server in the “apiStrict” field.

  property version: str

    The API version setting.

    This value is sent to the server in the “apiVersion” field.

class pymongo.server_api.ServerApiVersion

  An enum that defines values for `ServerApi.version`.

  Added in version 3.12.

  V1 = '1'

    Server API version “1”.