Package: python-dialpad
Python Dialpad API ClientA python wrapper around the Dialpad REST APIThis document describes the installation, usage, and development practices of this python library.
For information about the API itself, head on over to ourAPI Documentationpage!InstallationJust use everyone's favourite python package installer:pippipinstallpython-dialpadUsageThe Short VersionTL;DR, this library provides aDialpadClientclass, which can be instantiated with an API token
and a dialpad URL.Once aDialpadClientobject has been constructed, it can be used to call our API endpoints:fromdialpadimportDialpadClientdp_client=DialpadClient(sandbox=True,token='API_TOKEN_HERE')print(dp_client.user.get(user_id='1234567'))Client Constructor Argumentstoken (required)The API token that will be used to authenticate API requests.sandbox (optional)If thesandboxargument is set toTrue, then API calls will be
routed tohttps://sandbox.dialpad.com.base_url (optional)Routes requests to a specific url.API ResourcesIn general, each resource that we support in our public API will be exposed as properties of the
client object. For example, theUserresource can be accessed using theuserproperty (as
demonstrated above).Each of these resource properties will expose related HTTP methods as methods of that resource
property.For example,GET /api/v2/users/{id}translates todp_client.user.get('the_user_id').API ResponsesIn cases where our API responds with a single JSON object, the client method will return a Python
dict (as demonstrated above)In cases where our API responds with a paginated list of many JSON objects, the client method will
return an iterator which will lazily request the next page as the iterator is iterated upon.fromdialpadimportDialpadClientdp_client=DialpadClient(sandbox=True,token='API_TOKEN_HERE')foruserindp_client.user.list():print(user)DevelopmentTestingThat's right, the testing section is first in line! Before you start diving in, let's just make sure your environment is set up properly, and that the tests are running buttery-smooth.Assuming you've already cloned the repository, all you'll need to do is installtox, and run the command against the appropriate environment.Install thetoxpackage.$pipinstalltoxRun the tests$toxOptionaly, you can specify an environment to run the tests against. For eg:$tox-epy3That was easy :)Neato!Adding New ResourcesMost of the changes to this library will probably just be adding support for additional resources
and endpoints that we expose in the API, so let's start with how to add a new resource.Each resource exposed by this library should have its own python file under thedialpad/resourcesdirectory, and should define a singleclassthat inherits fromDialpadResource.The class itself should set the_resource_pathclass property to a list of strings such
that'/api/v2/' + '/'.join(_resource_path)corresponds to the API path for that resource.Once the_resource_pathis defined, the resource class can define instance methods to expose
functionality related to the resource that it represents, and can use theself.requesthelper
method to make authenticated requests to API paths under the_resource_path. For example,
if_resource_pathis set to['users'], then callingself.request(method='POST')would make
aPOSTrequest to/api/v2/users. (A more precise description of therequestmethod is given
in the following section)With that in mind, most methods that the developer chooses to add to a resource class will probably
just be a very thin method that passes the appropriate arguments intoself.request, and returns
the result.TherequestHelper Methodself.requestis a helper method that handles the details of authentication, response parsing, and
pagination, such that the caller only needs to specify the API path, HTTP method, and request data.
The method arguments are as follows:path (optional)Any additional path elements that should be added after the_resource_pathmethod (optional, default: 'GET')The HTTP methoddata (optional)A python dict defining either the query params or the JSON payload, depending on
which HTTP method is specifiedheaders (optional)Any additional headers that should be included in the request (the API key
is automatically included)If the request succeeds, thenself.requestwill either return a python dict, or an iterator of
python dicts, depending on whether the server responds with a pagenated response. Pagenated
responses will be detected automatically, so the caller does not need to worry about it.If the request fails, then arequests.HTTPErrorexception will be raised, and it'll be up to the
consumer of this library to deal with it 😎Theresources/__init__.pyFileWhen a new file is added to theresourcesdirectory, a new import statement should also be added
to__init__.pyto expose the newly defined resource class as a direct property of theresourcesmodule.DialpadClientResource PropertiesIn addition to adding the new class to the__init__.pyfile, the new resource class should also
be added as a cached property of theDialpadClientclass.RecapTo add a new resource to this client library, simply:Create a new file under theresourcesdirectoryDefine a new subclass ofDialpadResourcewithin said fileExpose methods related to that resource as methods on your new classAdd a new import statement inresources/__init__.pyAdd a new property to theDialpadClientclass