pyoneall - OneAll API Wrapper

OneAll (http://www.oneall.com) provides web-applications with a unified API for 30+ social networks. pyoneall provides developers with OneAll accounts a simple interface with the OneAll API for Python-based web-applications.

Implementation Overview

OneAll API documentation is available at http://docs.oneall.com. However, in order to use pyoneall with your application, it's enough to read the docs for the Connection API: Connection API Documentation.

So far, we have tested pyoneall within Flask and Django apps. To use OneAll as a Django authentication backend, please check out our django_oneall project, which relies on this package.

pyoneall defines the OneAll class, which is the API client. As of now, it has the following methods:

connections():	Get a list of social connections to the site
connection():	Get detailed connection data including user details
users():	Get a list of users that have connected with the site
user():	Get detailed user data
user_contacts():	Get a list of user's contacts
publish():	Publish a message using user's social network account

As pyoneall wraps a REST API which returns JSON objects, the objects returned by the methods behave in a somewhat JavaScript-like manner. This means that in addition to the dict-style object['key'] notation, you can also use object.key.

Also, arrays nested in the JSON responses, are represented by a class that defines a by_*() grouping and searching method in an addition to the list methods it inherits from.

For more information on these classes, check out help(pyoneall.base.OADict) and help(pyoneall.base.OAList).

Example

Authentication

Access to the OneAll API requires authentication. Obtain your API credentials following the procedure described at Authentication Documentation.

Create an instance of the OneAll client:

from pyoneall import OneAll

oa = OneAll(
    site_name='NAME OF YOUR ONEALL SITE',
    public_key='PUBLIC KEY OF YOUR SITE',
    private_key='PRIVATE KEY OF YOUR SITE'
)

The Connection API

Fetching connections lists

connections = oa.connections()

connections now contains the "connections" portion of the result of the API call, as described in http://docs.oneall.com/api/resources/connections/list-all-connections/. Full response data (for debugging and whatnot) is in connections.response.

OneAll uses pagination for calls which contain many entries. Each call returns a page up to 500 entries. When the OneAll.connections() method is executed without arguments, only the first page is loaded. You the access the pagination information in connections.pagination.

In order to load a custom range of pages, you can do something like:

connections = oa.connections(first_page=3, last_page=6)

Or, if you want to load all pages, use:

connections = oa.connections(fetch_all=True)

Of course, this will result in multiple API calls.

The connections list itself is in connections.entries:

>>> connections.entries
[{u'callback_uri': u'http://www.example.com/connect/',
 u'connection_token': u'cf2fffc7-34dc-484e-95cd-13f8ab838e22',
 u'date_creation': u'Sun, 23 Jun 2013 14:12:43 +0200',
 u'status': u'succeeded'},
{u'callback_uri': u'http://m.example.com/connect/',
 u'connection_token': u'4276bd23-3605-4679-acd2-963148c477cc',
 u'date_creation': u'Sun, 23 Jun 2013 14:13:20 +0200',
 u'status': u'succeeded'},
{u'callback_uri': u'http://www.example.com/connect/',
 u'connection_token': u'58ad2a04-ed1e-4799-a3ca-2b26651e35a0',
 u'date_creation': u'Sun, 23 Jun 2013 14:18:00 +0200',
 u'status': u'succeeded'},
{u'callback_uri': u'http://m.example.com/connect/',
 u'connection_token': u'e5231790-c6dc-4ce8-9922-792a2aebbba2',
 u'date_creation': u'Sun, 23 Jun 2013 14:18:11 +0200',
 u'status': u'succeeded'},
{u'callback_uri': u'http://www.example.com/connect/',
 u'connection_token': u'f82ad1e5-113f-46a2-b1c5-2a57a6002401',
 u'date_creation': u'Sun, 23 Jun 2013 14:21:14 +0200',
 u'status': u'succeeded'}]

In the example above, you can see that some connections were made with the callback of the desktop website (http://www.example.com/connect/), and some were made with the mobile webapp (http://m.example.com/connect/). We can get an object grouped by the "callback_uri" using:

>>> connections.entries.by_callback_uri()
{u'http://www.example.com/connect/': [
    {u'callback_uri': u'http://www.example.com/connect/',
     u'connection_token': u'cf2fffc7-34dc-484e-95cd-13f8ab838e22',
     u'date_creation': u'Sun, 23 Jun 2013 14:12:43 +0200',
     u'status': u'succeeded'},
    {u'callback_uri': u'http://www.example.com/connect/',
     u'connection_token': u'58ad2a04-ed1e-4799-a3ca-2b26651e35a0',
     u'date_creation': u'Sun, 23 Jun 2013 14:18:00 +0200',
     u'status': u'succeeded'}],
    {u'callback_uri': u'http://www.example.com/connect/',
     u'connection_token': u'f82ad1e5-113f-46a2-b1c5-2a57a6002401',
     u'date_creation': u'Sun, 23 Jun 2013 14:21:14 +0200',
     u'status': u'succeeded'},
 u'http://m.example.com/connect/': [
    {u'callback_uri': u'http://m.example.com/connect/',
     u'connection_token': u'4276bd23-3605-4679-acd2-963148c477cc',
     u'date_creation': u'Sun, 23 Jun 2013 14:13:20 +0200',
     u'status': u'succeeded'},
    {u'callback_uri': u'http://m.example.com/connect/',
     u'connection_token': u'e5231790-c6dc-4ce8-9922-792a2aebbba2',
     u'date_creation': u'Sun, 23 Jun 2013 14:18:11 +0200',
     u'status': u'succeeded'}]}

Or get a list of connections with a specific "callback_uri":

>>> connections.entries.by_callback_uri('http://m.example.com/connect/')
[{u'callback_uri': u'http://m.example.com/connect/',
 u'connection_token': u'4276bd23-3605-4679-acd2-963148c477cc',
 u'date_creation': u'Sun, 23 Jun 2013 14:13:20 +0200',
 u'status': u'succeeded'},
{u'callback_uri': u'http://m.example.com/connect/',
 u'connection_token': u'e5231790-c6dc-4ce8-9922-792a2aebbba2',
 u'date_creation': u'Sun, 23 Jun 2013 14:18:11 +0200',
 u'status': u'succeeded'}]

Reading connection details

In order to get the user_token and the user's social identity you can pass a connection_token to the connection() method of the OneAll instance:

some_connection = oa.connection('e5231790-c6dc-4ce8-9922-792a2aebbba2')

Or, alternatively you can fetch the connection details through the connection() method of an entry in the list of connections:

some_connection = connections.entries[3].connection()

some_connection will now contain the "connection" portion of the response described in the API documentation for Read Connection Details, most importantly some_connection.user and some_connection.user.user_token

The User API

Fetching user list

OneAll.users() behaves the same way OneAll.connections() does, arguments and all. This is due to the similarity of the List Users and the List Connections API, in terms of pagination and entries structure.

users = oa.users()

Now, you can access users.entries, or even access detailed user data with users.entries[4].user().

Reading user details

Read user details using:

user_token = some_connection.user.user_token
some_user = oa.user(user_token)

some_user will contain the "user" portion of the response detailed at http://docs.oneall.com/api/resources/users/read-user-details/.

Reading user's contacts

You can get the user's contacts (depending on the social network) with:

contacts = some_user.contacts()

or, with:

contacts = oa.user_contacts(user_token)

Publishing content on user's behalf

First, you need to format a message as described at http://docs.oneall.com/api/resources/users/write-to-users-wall/. Afterwards, publish it using publish():

message = {
    'request': {
        'message': {
            'parts': {
                'text': {
                    'body': 'Hello World!' }}}}}

oa.publish(user_token, message)

License

Copyright (c) 2013-2015, Leandigo (www.leandigo.com) Released under the MIT License. See the LICENSE file for details.