Low-Level Connection for HubSpot API Clients

https://travis-ci.org/2degrees/hubspot-connection.png?branch=master https://coveralls.io/repos/2degrees/hubspot-connection/badge.png?branch=master
Download:http://pypi.python.org/pypi/hubspot-connection
Sponsored by:2degrees Limited.

hubspot-connection provides a lightweight abstraction layer for making requests to the HubSpot API.

Here’s an example of how it can be used:

from hubspot.connection import APIKey
from hubspot.connection import PortalConnection

authentication_key = APIKey('HUBSPOT-API-KEY')
with PortalConnection(authentication_key, 'client') as connection:
    contacts_data = connection.send_get_request('/contacts/v1/contacts/statistics')
    print "Number of contacts: {}".format(contacts_data.get('contacts'))

This project is officially supported under Python 2.7, but may work with Python 2.6 and Python 3.

Tutorial

Authentication

HubSpot supports two authentication methods: OAuth and a proprietary, token-based method referred to as “API Key”.

In order to authenticate you just need to instanciate either hubspot.connection.OAuthKey or hubspot.connection.APIKey with the apropriate value.

Example:

authentication_key = OAuthKey('HUBSPOT-OAUTH-KEY')

authentication_key = APIKey('HUBSPOT-API-KEY')

How to make requests to HubSpot

PortalConnection is meant to be used as a context manager which takes care of keeping the connection alive retrying a maximum of 3 times should there be any network-level timeout or socket errors.

A good example of a library using hubspot.connection can be seen here: hubspot-contacts.

Testing

hubspot-connection comes bundled with utilities designed to help you with testing.

The MockPortalConnection is initialized with zero or more so-called “api call simulators” (or simply “simulators”), which are passed by position. Simulators are callables that receive no arguments and return an iterable of successful or unsuccessful API calls.

Their role, is to tell the MockPortalConnection what API calls are excepted to be called, and that each will have exactly the expected:

  • URL path
  • Body deserialization
  • URL arguments
  • Method

If the response is expected to be successful, it’s body deserialization will be verified, if the response is expected to be unsuccessful, the exception will be checked, whether it’s the correct one. To represent API calls this library comes with SuccessfulAPICall and UnsuccessfulAPICall.

Should any unexpected API end-point get called, any of the expected end-points is not called or if they are in the wrong order, an AssertionError is raised.

Example of an API call:

# Example of a successful API call
api_call = SuccessfulAPICall(
    '/foo/bar',
    'GET',
    response_body_deserialization={'foo': 'bar'},
)

# Example of an unsuccessful API call
api_call = UnsuccessfulAPICall(
    '/foo/bar',
    'GET',
    exception=HubspotServerError('Foo is not implemented', 501),
)

Example of testing the deletion of a contact list:

from hubspot.connection.testing import MockPortalConnection
from hubspot.connection.testing import SuccessfulAPICall

def test_delete_contact_list():
    list_id = 1
    url_path = '/contacts/v1/lists/{}'.format(list_id)

    api_call = SuccessfulAPICall(
        url_path,
        'DELETE',
        response_body_deserialization=None,
    )

    expected_api_calls_simulator = lambda : [api_call]

    with MockPortalConnection(expected_api_calls_simulator) as connection
        delete_list(list_id, connection)

# Unit to be tested
def delete_contact_list(list_id, connection):
    connection.send_delete_request('/contacts/v1/lists/{}'.format(list_id))

API

Authentication

class hubspot.connection.APIKey

Representation of the HubSpot API Key

key_value

The HubSpot API Key (hapikey)

class hubspot.connection.OAuthKey

Representation of the HubSpot OAuth Key

key_value

The HubSpot OAuth Key (access_token)

Connection

class hubspot.connection.PortalConnection(authentication_key, change_source)

Connection to HubSpot

Parameters:
  • authentication_key – This can be either an APIKey or an OAuthKey instance
  • change_source (basestring) – The string passed to HubSpot as auditId in the query string
send_delete_request(url_path)

Send a DELETE request to HubSpot

Parameters:url_path (basestring) – The URL path to the endpoint
Returns:Decoded version of the JSON that HubSpot put in the body of the response.
send_get_request(url_path, query_string_args=None)

Send a GET request to HubSpot

Parameters:
  • url_path (basestring) – The URL path to the endpoint
  • query_string_args (dict) – The query string arguments
Returns:

Decoded version of the JSON that HubSpot put in the body of the response.

send_post_request(url_path, body_deserialization)

Send a POST request to HubSpot

Parameters:
  • url_path (basestring) – The URL path to the endpoint
  • body_deserialization (dict) – The request’s body message deserialized
Returns:

Decoded version of the JSON that HubSpot put in the body of the response.

send_put_request(url_path, body_deserialization)

Send a PUT request to HubSpot

Parameters:
  • url_path (basestring) – The URL path to the endpoint
  • body_deserialization – The request’s body message deserialized
Returns:

Decoded version of the JSON that HubSpot put in the body of the response.

Exceptions

exception hubspot.connection.exc.HubspotAuthenticationError(msg, request_id)

HubSpot rejected your authentication key. This represents an HTTP response code of 401.

exception hubspot.connection.exc.HubspotClientError(msg, request_id)

HubSpot deemed the request invalid. This represents an HTTP response code of 40X, except 401

Parameters:request_id (unicode) –
exception hubspot.connection.exc.HubspotException

The base HubSpot error.

exception hubspot.connection.exc.HubspotServerError(msg, http_status_code)

HubSpot failed to process the request due to a problem at their end. This represents an HTTP response code of 50X.

Parameters:http_status_code (int) –

Testing utilities

class hubspot.connection.testing.MockPortalConnection(*api_calls_simulators)

Mock representation of a PortalConnection

class hubspot.connection.testing.APICall(*values_by_field_order, **values_by_field_name)
url_path

A basestring representing the complete URL to the request

http_method

A basestring representing the HTTP Method to the request

query_string_args

A dict representing the query string args

request_body_deserialization

A representation of the request’s body

class hubspot.connection.testing.SuccessfulAPICall
Base:APICall
response_body_deserialization

A represention of the response’s body

class hubspot.connection.testing.UnsuccessfulAPICall
Base:APICall
exception

An exception representing the raised Exception

Support

For questions directly related to hubspot-connection, please use our 2degrees-floss mailing list.

Please go to our development site at GitHub to get the latest code, create pull requests and raise issues.

Changelog

Version 1.0 Release Candidate 1 (2014-06-23)

This is the first public release.

Version 1.0 Release Candidate 2 (2014-07-14)

  • Added content-type=’application/json’ for requests with body

Version 1.0 Release Candidate 3 (2014-09-15)

  • Made content-type mandatory only when content is expected

Version 1.0 Release Candidate 4 (2015-02-18)

  • Allowed for extra details in error responses from Hubspot