Quickstart Guide

A REST Client Example

Note that the following is all fictitious data. What is received from and sent to an API is unique to every API. Do not copy and paste these examples.

Connecting with an API

import drest
api = drest.API('http://localhost:8000/api/v1/')

Authentication

By default, drest.api.API.auth() implements HTTP Basic Authentication. This is generally overridden however by specific API’s that subclass from api.API().

api.auth('john.doe', 'my_password')

Note that authentication may not be necessary for your use case, or for read-only API’s.

Making Requests

Requests can be made openly by specifying the method (GET, PUT, POST, DELETE, ...), as well as the path (after the baseurl).

# GET http://localhost:8000/api/v1/users/1/
response = api.make_request('GET', '/users/1/')

Additionally, you can add a resource which makes access to the API more native and programatic.

# Add a basic resource (assumes path='/users/')
api.add_resource('users')

# A list of available resources is available at:
api.resources

# GET http://localhost:8000/api/v1/users/
response = api.users.get()

# GET http://localhost:8000/api/v1/users/1/
response = api.users.get(1)

Creating a resource only requires a dictionary of ‘parameters’ passed to the resource:

user_data = dict(
    username='john.doe',
    password='oober-secure-password',
    first_name='John',
    last_name='Doe',
    )

# POST http://localhost:8000/api/v1/users/
response = api.users.post(user_data)

Updating a resource is as easy as requesting data for it, modifying it, and sending it back

response = api.users.get(1)
updated_data = response.data.copy()
updated_data['first_name'] = 'John'
updated_data['last_name'] = 'Doe'

# PUT http://localhost:8000/api/v1/users/1/
response = api.users.put(1, updated_data)

Deleting a resource simply requires the primary key:

# DELETE http://localhost:8000/api/v1/users/1/
response = api.users.delete(1)

Working With Return Data

Every call to an API by default returns a drest.response.ResponseHandler object. The two most useful members of this object are:

  • response.status (http status code)
  • response.data (the data returned by the api)

If a serialization handler is used, then response.data will be the unserialized form (Python dict).

The Response Object

response = api.users.get()
response.status # 200
response.data # dict

Developers can base conditions on the status of the response (or other fields):

response = api.users.get()
if response.status != 200:
    print 'Uhoh.... we didn't get a good response.'

The data returned from a request is the data returned by the API. This is generally JSON, YAML, XML, etc... however if a Serialization handler is enabled, this will be a python dictionary. See drest.serialization.

response.data:

{
    u'meta':
        {
            u'previous': None,
            u'total_count': 3,
            u'offset': 0,
            u'limit': 20,
            u'next':
            None
        },
    u'objects':
        [
            {
                u'username': u'john.doe',
                u'first_name': u'John',
                u'last_name': u'Doe',
                u'resource_pk': 2,
                u'last_login': u'2012-01-26T01:21:20',
                u'resource_uri': u'/api/v1/users/2/',
                u'id': u'2',
                u'date_joined': u'2008-09-04T14:25:29'
            }
        ]
}

The above is fictitious data returned from a TastyPie API. What is returned by an API is unique to that API therefore you should expect the ‘data’ to be different that the above.

Connecting Over SSL

Though this is documented elsewhere, it is a pretty common question. Often times API services are SSL enabled (over https://) but do not possess a valid or active SSL certificate. Anytime an API service has an invalid, or usually self-signed certificate, you will receive an SSL error similar to:

[Errno 1] _ssl.c:503: error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

In order to work around such situations, simply pass the following to your api:

api = drest.API('https://example.com/api/v1/', ignore_ssl_validation=True)