-
Notifications
You must be signed in to change notification settings - Fork 118
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
6 changed files
with
433 additions
and
71 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,200 @@ | ||
| # Vonage Python SDK v3 to v4 Migration Guide | ||
|
|
||
| This is a guide to help you migrate from using v3 of the Vonage Python SDK to using the new v4 `vonage` package. It has feature parity with the v3 package and contains many enhancements and structural changes. We will only be supporting v4 from its release. | ||
|
|
||
| The Vonage Python SDK (`vonage`) contains methods and data models to help you use many of Vonage's APIs. It also includes support for the new network APIs announced by Vonage. | ||
|
|
||
| ## Contents | ||
|
|
||
| - [Structural Changes and Enhancements](#structural-changes-and-enhancements) | ||
| - [Installation](#installation) | ||
| - [Configuration](#configuration) | ||
| - [Accessing API Methods](#accessing-api-methods) | ||
| - [Accessing API Data Models](#accessing-api-data-models) | ||
| - [Response Objects](#response-objects) | ||
| - [API Changes](#API-changes) | ||
| - [Additional Resources](#additional-resources) | ||
|
|
||
| ## Structural Changes and Enhancements | ||
|
|
||
| Here are some key changes to the SDK: | ||
|
|
||
| 1. v4 of the Vonage Python SDK now uses a monorepo structure, with different packages for calling different Vonage APIs all using common code. You don't need to install the different packages directly as the top-level `vonage` package pulls them in and provides a common and consistent way to access methods. | ||
| 2. The v4 SDK makes heavy use of [Pydantic data models](https://docs.pydantic.dev/latest/) to make it easier to call Vonage APIs and parse the results. This also enforces correct typing and makes it easier to pass the right objects to Vonage. | ||
| 3. Docstrings have been added to methods and data models across the whole SDK to increase quality-of-life developer experience and make in-IDE development easier. | ||
| 4. Many new custom errors have been added for finer-grained debugging. Error objects now contain more information and error messages give more information and context. | ||
| 5. Support has been added for all [Vonage Video API](https://developer.vonage.com/en/video/overview) features, bringing it to feature parity with the OpenTok package. See [the OpenTok -> Vonage Video migration guide](video/OPENTOK_TO_VONAGE_MIGRATION.md) for migration assistance. If you're using OpenTok, migration to use v4 of the Vonage Python SDK rather than the `opentok` Python package is highly recommended. | ||
| 6. APIs that have been deprecated by Vonage, e.g. Meetings API, have not been implemented in v4. Objects deprecated in v3 of the SDK have also not been implemented in v4. | ||
|
|
||
| ## Installation | ||
|
|
||
| The most common way to use the new v4 package is by installing the top-level `vonage` package, similar to how you would install v3. The difference is that the new package will install the other Vonage API packages as dependencies. | ||
|
|
||
| To install the Python SDK package using pip: | ||
|
|
||
| ```bash | ||
| pip install vonage | ||
| ``` | ||
|
|
||
| To upgrade your installed client library using pip: | ||
|
|
||
| ```bash | ||
| pip install vonage --upgrade | ||
| ``` | ||
|
|
||
| You will notice that the dependent Vonage packages have been installed as well. | ||
|
|
||
| ## Configuration | ||
|
|
||
| To get started with the v4 SDK, you'll need to initialize an instance of the `vonage.Vonage` class. This can then be used to access API methods. You need to provide authentication information and can optionally provide configuration options for the HTTP Client that's used (that is in the `vonage-http-client` package). This section will break all of this down then provide an example. | ||
|
|
||
| ### Authentication | ||
|
|
||
| Depending on the Vonage API you want to use, you'll use different forms of authentication. You'll need to provide either an API key and secret or the ID of a Vonage Application and its corresponding private key. This is done by initializing an instance of `vonage.Auth`. | ||
|
|
||
| ```python | ||
| from vonage import Auth | ||
|
|
||
| # API key/secret authentication | ||
| auth = Auth(api_key='your_api_key', api_secret='your_api_secret') | ||
|
|
||
| # Application ID/private key authentication | ||
| auth = Auth(application_id='your_api_key', private_key='your_api_secret') | ||
| ``` | ||
|
|
||
| This `auth` can then be used when initializing an instance of `vonage.Vonage` (example later in this section). | ||
|
|
||
| ### Setting HTTP Client Options | ||
|
|
||
| The HTTP client used to make requests to Vonage comes with sensible default options, but if you need to change any of these, create a `vonage.HttpClientOptions` object and pass that in to `vonage.Vonage` when you create the object. | ||
|
|
||
| ```python | ||
| # Create HttpClientOptions instance with some non-default settings | ||
| options = HttpClientOptions(api_host='new-api-host.example.com', timeout=100) | ||
| ``` | ||
|
|
||
| ### Example | ||
|
|
||
| Putting this all together, to set up an instance of the `vonage.Vonage` class to call Vonage APIs, do this: | ||
|
|
||
| ```python | ||
| from vonage import Vonage, Auth, HttpClientOptions | ||
|
|
||
| # Create an Auth instance | ||
| auth = Auth(api_key='your_api_key', api_secret='your_api_secret') | ||
|
|
||
| # Create HttpClientOptions instance | ||
| # (not required unless you want to change options from the defaults) | ||
| options = HttpClientOptions(api_host='new-api-host.example.com', timeout=100) | ||
|
|
||
| # Create a Vonage instance | ||
| vonage = Vonage(auth=auth, http_client_options=options) | ||
| ``` | ||
|
|
||
| ## Accessing API Methods | ||
|
|
||
| To access methods relating to Vonage APIs, you'll create an instance of the `vonage.Vonage` class and access them via named attributes, e.g. if you have an instance of `vonage.Vonage` called `vonage_client`, use this syntax: | ||
|
|
||
| ```python | ||
| vonage_client.vonage_api.api_method(...) | ||
|
|
||
| # E.g. | ||
| vonage_client.video.create_session(...) | ||
| ``` | ||
|
|
||
| This is very similar to the v3 SDK. | ||
|
|
||
| ## Accessing API Data Models | ||
|
|
||
| Unlike the methods to call each Vonage API, the data models and errors specific to each API are not accessed through the `vonage` package, but are instead accessed through the specific API package. | ||
|
|
||
| For most APIs, data models and errors can be accessed from the top level of the API package, e.g. to send a Verify request, do this: | ||
|
|
||
| ```python | ||
| from vonage_verify_v2 import VerifyRequest, SmsChannel | ||
|
|
||
| sms_channel = SmsChannel(to='1234567890') | ||
| verify_request = VerifyRequest(brand='Vonage', workflow=[sms_channel]) | ||
|
|
||
| response = vonage_client.verify_v2.start_verification(verify_request) | ||
| print(response) | ||
| ``` | ||
|
|
||
| However, some APIs with a lot of models have them located under the `vonage_api_package.models` package, e.g. `vonage-messages`, `vonage-voice` and `vonage-video`. To access these, simply import from `.models`, e.g. to send an image via Facebook Messenger do this: | ||
|
|
||
| ```python | ||
| from vonage_messages.models import MessengerImage, MessengerOptions, MessengerResource | ||
|
|
||
| messenger_image_model = MessengerImage( | ||
| to='1234567890', | ||
| from_='1234567890', | ||
| image=MessengerResource(url='https://example.com/image.jpg'), | ||
| messenger=MessengerOptions(category='message_tag', tag='invalid_tag'), | ||
| ) | ||
|
|
||
| vonage_client.messages.send(message) | ||
| ``` | ||
|
|
||
| ## Response Objects | ||
|
|
||
| In v3 of the SDK, the APIs returned Python dictionaries. In v4, almost all responses are now deserialized from the returned JSON into Pydantic models. Response data models are accessed in the same way as the other data models above and are also fully documented with useful docstrings. | ||
|
|
||
| If you want to convert the Pydantic responses into dictionaries, just use the `model_dump` method on the response. For example: | ||
|
|
||
| ```python | ||
| from vonage_account import SettingsResponse | ||
|
|
||
| settings: SettingsResponse = vonage_client.account.update_default_sms_webhook( | ||
| mo_callback_url='https://example.com/sms_webhook', | ||
| dr_callback_url='https://example.com/delivery_receipt_webhook', | ||
| ) | ||
|
|
||
| print(settings.model_dump()) | ||
| ``` | ||
|
|
||
| Response fields are also converted into snake_case where applicable, so as to be more pythonic. This means they won't necessarily match the API one-to-one. | ||
|
|
||
| ## API Changes | ||
|
|
||
| In v3, you access `vonage.Client`. In v4, it's `vonage.Vonage`. | ||
|
|
||
| The methods to get and set host attributes in v3 e.g. `vonage.Client.api_host` have been removed. You now get these options in v4 via the `vonage.Vonage.http_client`. Set these options in v4 by adding the options you want to the `vonage.HttpClientOptions` data model when initializing a `vonage.Vonage` object. | ||
|
|
||
| Rather than just returning a `ClientError` when an HTTP Client error is thrown, we now throw more specific errors with more information. | ||
|
|
||
| ### Specific API Changes | ||
|
|
||
| The process for verifying a number using the Network Number Verification API has been simplified. In v3 it was required to exchange a code for a token then use this token in the verify request. In v4, these steps are combined so both functions are taken care of in the `NetworkNumberVerification.verify` method. | ||
|
|
||
| Verify v2 functionality is accessed from `verify2` in v3 and `verify_v2` in v4. | ||
|
|
||
| SMS message signing/verifying signatures code in `vonage.Client` in v3 has been moved into the `vonage-http-client` package in v4. This can be accessed via the `vonage` package as we import the `vonage-http-client.Auth` class into its namespace. | ||
|
|
||
| Old method -> new method | ||
| `vonage.Client.sign_params` -> `vonage.Auth.sign_params` | ||
| `vonage.Client.check_signature` -> `vonage.Auth.check_signature` | ||
|
|
||
| ### Method Name Changes | ||
|
|
||
| Some methods from v3 have had their names changed in v4. Assuming you access all methods from the `vonage.Vonage` class in v4 with `vonage.Vonage.api_method` or the `vonage.Client` class in v3 with `vonage.Client.api_method`, this table details the changes: | ||
|
|
||
| | 3.x Method Name | 4.x Method Name | | ||
| |-----------------|-----------------| | ||
| | `account.topup` | `account.top_up` | | ||
| | `messages.send_message` | `messages.send` | | ||
| | `messages.revoke_outbound_rcs_message` | `messages.revoke_rcs_message` | | ||
| | `number_insight.get_basic_number_insight` | `number_insight.basic_number_insight` | | ||
| | `number_insight.get_standard_number_insight` | `number_insight.standard_number_insight` | | ||
| | `number_insight.get_advanced_number_insight` | `number_insight.advanced_sync_number_insight` | | ||
| | `number_insight.get_async_advanced_number_insight` | `number_insight.advanced_async_number_insight` | | ||
| | `numbers.get_account_numbers` | `numbers.list_owned_numbers` | | ||
| | `numbers.get_available_numbers` | `numbers.search_available_numbers` | | ||
| | `sms.send_message` | `sms.send` | | ||
| | `verify.psd2` | `verify.start_psd2_verification` | | ||
| | `verify.check` | `verify.check_code` | | ||
| | `verify.check` | `verify.check_code` | | ||
| | `verify2.new_request` | `verify_v2.start_verification` | | ||
| | `video.set_stream_layout` | `video.change_stream_layout` | | ||
|
|
||
| ## Additional Resources | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.