Skip to main content

A wrapper for REST APIs

Project description

syndicate - A wrapper for REST APIs

Abstraction for HTTP based REST APIs. This provides a means to generically
handle serialization (JSON) and URI mapping as seen in many of the REST APIs
published these days. Currently Tastypie APIs are the primary target but the
system should be compossible enough to work with other APIs if they work
roughly the same way.


* Requests (sync mode)
* Tornado (async mode)


python ./ build
python ./ install


* Python 2.7
* Python 3.3+


* Unified authentication between HTTP adapters.
* Documentation

Getting Started

Syndicate has two basic modes for communicating with an API, sync and async.
The sync mode uses the 'requests' library as the HTTP adapter and the async
mode uses the 'tornado' web framework. An adapter can be provided by the
user if they have their own backend to use too; Twisted for example.

In either mode, your interface is a 'Service' instance, which facilitates
authentication, session management (via an adapter) and serialization.

Synchronous Examples

**Creating a connnection**

Instantiate a service class with some basic descriptions of the remote API
to get a persistent connection.

import syndicate

bakery = syndicate.Service(uri='https://a.bakery.fake', urn='/api/v1/',
auth=('mrpresident', '1000xlight_points'))

**Simple GET**

Fetch all the resources at https://a.bakery.fake/api/v1/cake/

for x in bakery.get('cake'):
print("Cake is food:", x)

**Delete with filter**

Keyword arguments are converted to URL queries. To filter by an exact
field match such as https://a.bakery.fake/api/v1/cake/?type=cheese we
simply add the 'type' keyword to the <verb>() call. This example deletes
all cheese cakes because I hate cheese.

for x in bakery.get('cake', type='cheese'):

**Update a resource**

Resources implement the mapping protocol so they work like dictionaries.

default = bakery.get('condiment', default=True)
if 'pepper' not in def['items']:
print("We already serve pepper by default")

**Adding a new resource**

new_owl ='cake', {
"type": "chuck_norris",
"name": "Round House",
"scovilles": 16000000001 # sorry resiniferatoxin

**Fetching a subresource**

A subresource is probably what you would expect, a resource inside another
resource. Here we get, https://a.bakery.fake/api/v1/thing/100/subthing/.

thing = bakery.get('thing', 100)
subthing = thing.fetch('subthing')

**Non CRUD methods**

If your service has non CRUD methods, you can ask a service to "do" things
directly. Let's "BAKE /api/v1/cake/100" with some instructions in the content

```python'bake', 'cake', 100, temp=420, time=3600)

Asynchronous Examples

Async service connections use Tornado,
If this is your first time doing async programming or using tornado, you
should get familiar with it first.

Tornado Docs:

The examples below assume you are running your code from a IOLoop callback
in the same thread as the IOLoop runner. Most of the calls made to an
async service return concurrent.Future objects so you can use all the
fun patterns available to Tornado applications.

**Creating a service connnection with Basic auth**
import syndicate

bakery = syndicate.Service(uri='https://a.bakery.fake', urn='/api/v1/',
auth=('mrpresident', '1000xlight_points'),

**Using Future objects directly (good)**

future_result = bakery.get('cake')

def handle_response(f):
for x in f.result():
print("Cake is food:", x)


**Using Future objects indirectly (better)**
def handle_response(f):
for x in f.result():
print("Cake is food:", x)

bakery.get('cake', callback=handle_response)

**Using Future objects as yield points (best)**

NOTE: You must using the @tornado.gen.coroutine decorator from your IOLoop
callback. A typical example is a web server URL handler that needs to fetch
foreign data.

def my_application_hook():
cakes = yield bakery.get('cake')
for x in cakes:
print("Cake is food:", x)
return cakes

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

syndicate-0.99.5.tar.gz (9.1 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page