bigcommerce-api 0.10.1
(Deprecated) Connect Python applications with the Bigcommerce API
License: MIT
Keywords: bigcommerce api client

Bigcommerce API V2 - Python Client
==================================

**Note:** The Bigcommerce API client is now located in the
`bigcommerce <https://pypi.python.org/pypi/bigcommerce>`__ package.

Wrapper over the ``requests`` library for communicating with the
Bigcommerce v2 API.

Needs ``requests`` and ``streql`` (run ``pip install bigcommerce-api``
for easiest way to install), and ``nose`` and ``vcrpy`` to run the
tests.

Usage
-----

Connecting
~~~~~~~~~~

.. code:: python

    import bigcommerce

    # OAuth2-based connection
    # Access_token is optional, if you don't have one you can use oauth_fetch_token (see below)
    api = bigcommerce.api.BigcommerceApi(client_id='', store_hash='', access_token='')

    # Legacy Basic authentication
    api = bigcommerce.api.BigcommerceApi(host='https://store.mybigcommerce.com', auth=('username', 'api token'))

``BigcommerceApi`` also provides two helper methods for connection with
OAuth2:

-  ``api.oauth_fetch_token(client_secret, client_secret, code, context, scope, redirect_uri)``
   – fetches and returns an access token for your application. As a side
   effect, configures ``api`` to be ready for use.

-  ``BigcommerceApi.oauth_verify_payload(signed_payload, client_secret)``
   – Returns user data from a signed payload.

Accessing and objects
~~~~~~~~~~~~~~~~~~~~~

The ``api`` object provides access to each API resource, each of which
provides CRUD operations, depending on capabilities of the resource:

.. code:: python

    api.Products.all()                         # GET /products
    api.Products.get(1)                        # GET /products/1
    api.Products.create(name='', type='', ...) # POST /products
    api.Products.get(1).update(price='199.90') # PUT /products/1
    api.Products.delete_all()                  # DELETE /products
    api.Products.get(1).delete()               # DELETE /products/1

The client provides full access to subresources, both as independent
resources:

::

    api.ProductOptions.get(1)                  # GET /products/1/options
    api.ProductOptions.get(1, 2)               # GET /products/1/options/2

And as helper methods on the parent resoource:

::

    api.Products.get(1).options()              # GET /products/1/options
    api.Products.get(1).options(1)             # GET /products/1/options/1

These subresources implement CRUD methods in exactly the same way as
regular resources:

::

    api.Products.get(1).options(1).delete()

Filters
~~~~~~~

Filters can be applied to ``all`` methods as keyword arguments:

.. code:: python

    customer = api.Customers.all(first_name='John', last_name='Smith')[0]
    orders = api.Orders.all(customer_id=customer.id)

Error handling
~~~~~~~~~~~~~~

Minimal validation of data is performed by the client, instead deferring
this to the server. A ``HttpException`` will be raised for any unusual
status code:

-  3xx status code: ``RedirectionException``
-  4xx status code: ``ClientRequestException``
-  5xx status code: ``ServerException``

The low level API
-----------------

The high level API provided by ``bigcommerce.api.BigcommerceApi`` is a
wrapper around a lower level api in ``bigcommerce.connection``. This can
be accessed through ``api.connection``, and provides helper methods for
get/post/put/delete operations.

Further documentation
---------------------

Full documentation of the API is available at
`developer.bigcommerce.com <http://developer.bigcommerce.com>`__

To do
-----

-  Count endpoints
-  Automatic enumeration of multiple page responses