Happy Business Starts Here

Highlighted
Zuora Support Moderator

How to Generate a Code Library From the Zuora OpenAPI Spec

The Zuora OpenAPI spec is a structured description of the Zuora REST API that follows the OpenAPI (also known as Swagger) standard. As a developer, you can use an open source tool to generate code libraries from our OpenAPI spec, so that you can easily integrate with the Zuora REST API via your preferred programming language.

 

Note: The Zuora API Reference is a visualization of our OpenAPI spec.

 

This post demonstrates how to use swagger-codegen to generate a Python library for the Zuora REST API. This post also demonstrates how to get started using the Python library.

 

Generate a Python Library for the Zuora REST API

 

You can download and install swagger-codegen on your local machine, but a simpler way to use swagger-codegen is to call the Swagger Generator web service.

 

To generate a Python library from our OpenAPI spec:

 

  1. Use a tool such as cURL or Postman to request a Python library from the Swagger Generator web service.

    For example:

    curl -X POST -H "Content-Type: application/json" -d '{"swaggerUrl":"https://www.zuora.com/wp-content/themes/zuora/yaml/swagger.yaml"}' https://generator.swagger.io/api/gen/clients/python
    

    The JSON response body contains a link to the generated Python library:

    {
      "code": "980274ca-bbd1-4482-b68b-c4e098c4544b",
      "link": "https://generator.swagger.io/api/gen/download/980274ca-bbd1-4482-b68b-c4e098c4544b"
    }
    
  2. Download the Python library using the link that the Swagger Generator web service returned.

    The Python library is provided in a ZIP file.

  3. Extract the ZIP file, then install the Python library according to the instructions the README.md file that comes with the Python library.

The Python library is called swagger_client.

 

Use the Python Library to Call the Zuora REST API

 

To use the Python library that you generated, create a Python script that imports swagger_client. There is an example in README.md that shows a basic script, but this script will not work without some modifications.

 

The following Python script demonstrates how to authenticate to the Zuora APISandbox environment via OAuth, then retrieve the details of a customer account.

 

Before running the script, set the client ID and client secret of an OAuth client. For more information about OAuth authentication, see https://www.zuora.com/developer/api-reference/#section/Authentication.

 

from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint

# Create an API client for the APISandbox environment
api_client = swagger_client.ApiClient()
api_client.configuration.host = 'https://rest.apisandbox.zuora.com'

# Generate an OAuth token
oauth_client_id = 'YOUR_CLIENT_ID'
oauth_client_secret = 'YOUR_CLIENT_SECRET'
oauth_api = swagger_client.OAuthApi(api_client)
try:
  oauth_api_response = oauth_api.create_token(oauth_client_id, oauth_client_secret, 'client_credentials')
  oauth_token = oauth_api_response.access_token
except ApiException as e:
  print("Exception: %s\n" % e)

# NOTE: Don't generate a new token for each API call; use the token until it expires

# Use the OAuth token for authentication
api_client.set_default_header('Authorization', 'Bearer %s' % oauth_token)

# Get a customer account
accounts_api = swagger_client.AccountsApi(api_client)
try:
  account_number = 'A00000079'
  accounts_api_response = accounts_api.g_et_account(account_number)
  pprint(accounts_api_response)
except ApiException as e:
  print("Exception: %s\n" % e)

 

When you run this script, Python prints an object that contains the details of account A00000079. For example:

{'basic_info': {'account_number': 'A00000079',
                'batch': 'Batch1',
                'communication_profile_id': '2c92c0f9446cd49501447539d6a76000',
                'crm_id': '',
                'id': '2c92c0f95be68649015bf14e001f2760',
                'invoice_template_id': '2c92c0f849369b8801493bf4e0bd432b',
                'name': 'London Taxi Company',
                'notes': '',
                'parent_id': None,
                'sales_rep': '',
                'status': 'Active',
                'tags': None},
 'bill_to_contact': {...},
 'billing_and_payment': {...},
 'metrics': {...},
 'sold_to_contact': {...},
 'success': True,
 'tax_info': {...}}

 

Troubleshooting

 

The Python library requires TLS version 1.2. If your Python distribution does not support TLS version 1.2, you will receive the following error when you run the script:

WARNING Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLError(1, u'[SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:590)'),)': /oauth/token

 

If you receive this error, you should install an up-to-date Python distribution.

 

This step will likely be necessary if you're using the Python distribution that comes with macOS. To install an up-to-date Python 2 distribtion on macOS, see https://docs.python-guide.org/starting/install/osx/.

 

For more information about Python and TLS, see http://pyfound.blogspot.com/2017/01/time-to-upgrade-your-python-tls-v12.html.