Getting Started¶

Repose allows you to declaratively define a client for restful APIs. There are three steps to getting started:

Define your resources
Configure your API
Try it out

1. Define your resources¶

Each Resource you define will generally map to a resource in your Api. Using GitHub’s API as an example:

class User(Resource):
    id = fields.Integer()
    login = fields.String()
    avatar_url = fields.String()
    location = fields.String()
    site_admin = fields.Boolean()

    class Meta:
        # Endpoint for getting a single specific user
        endpoint = '/users/{login}'
        # Endpoint for listing all users
        endpoint_list = '/users'


class Repository(Resource):
    id = fields.Integer()
    name = fields.String()
    full_name = fields.String()
    description = fields.String()
    owner = fields.Embedded(User)

    class Meta:
        # Endpoint for getting a single specific repository
        endpoint = '/repos/{full_name}'
        # Endpoint for listing all repositories
        endpoint_list = '/repositories'

This represents a very small subset of the available GitHub API, but it serves well as a demonstration.

2. Configure your API¶

To configure your API you need to instantiate an Api class. You can customise the Api’s behaviour either through parameters to __init__() or by defining your own subclass of Api.

In addition to providing high-level configuration, the Api instance must also be made aware of all available resources.

For example:

# A simple example of directly instantiating the Api class
github_api = Api(base_url='https://api.github.com')
github_api.register_resource(User)
github_api.register_resource(Repository)

Or, using extension:

# Alternatively, extend the Api class for added customisation options
class GitHubApi(Api):
    base_url = 'https://api.github.com'
    resources = [User, Repository]

github_api = GitHubApi()

The former is simpler, whereas the latter provides more flexibility for overriding the base Api class functionality.

3. Try it out¶

Now let’s try it out and get some resources:

>>> # Provide the login to get a user
>>> # (as this is what we specified in Meta.endpoint)
>>> User.objects.get(login='adamcharnock')
<User(login=u'adamcharnock', site_admin=None, id=138215, avatar_url=u'https://avatars.githubusercontent.com/u/138215?v=3', location=u'London, UK')>

>>> # Provide the full_name to get a repository
>>> # (again, as this is what we specified in Meta.endpoint)
>>> seed_repo = Repository.objects.get(full_name='adamcharnock/seed')
>>> print seed_repo.description
A utility for easily creating and releasing Python packages

>>> # The repo's owner attribute will give us a User resource
>>> # as this is an `Embedded` field
>>> seed_repo.owner
<User(login=u'adamcharnock', site_admin=None, id=138215, avatar_url=u'https://avatars.githubusercontent.com/u/138215?v=3', location=None)>

Ok, now let’s get a list of all repositories:

>>> Repository.objects.count()
100 # That cannot be right...
>>> repos = Repository.objects.all()
>>> len(repos)
100

So we get some results, but only a hundred repositories in GitHub? That definitly sounds wrong. What is going on here then?

Todo

Implement pagination support

Todo

Discuss limitations of count(). Link into ‘Using Managers’ document where we’ll discuss customising managers to provide this functionality.