api_api

This is a companion library to api, which provides an HTTP api to a django-based website. api_api provides a python interface to a website which uses api. For example, api provides the method api/describe_role:

from api_api import API

mysite = API('https://mysite.com', ['~/.mysite/config'])
role_description = mysite.api.describe_role(role)
print(role_description.name)

Setup

• Install api_api

  pip install api_api

• Get a key and its secret for your user from your website. The key will be k-, and 16 hex digits, such as k-e99af68faae6ab92, and the secret will be 40 random characters, such as: dgIjbuzYCj1hgedO6Df9vwJ2oGAoHzWJSfYSqcTS.

• There are now two options:

  Use the Key and Secret

  Without further setup, the key and secret can be used immediately:

  mysite = API('https://mysite.com/api')
  session = mysite(key_id="your key here", key_secret="your key's secret here")
  role_description = session.api.describe_role(role)
  

  Store your configuration

  configuration can be stored in config files (eg ~/.mysite/config). The default configuration allows the quickest use. If you set up ~/.mysite/config like this:

  default:
  access_key_id = your key here
  access_key_secret = your key's secret here
  

  the api can be used like this:

  mysite = API('https://mysite.com/api', '~/mysite/config')
  role_description = mysite.api.describe_role(role)
  

  Using the API directly uses the default profile.

  Many profiles can be set - to use a non-default one in your setup file:

  my_own_profile:
  access_key_id = your own key here
  access_key_secret = your own key's secret here
  

  And in python:

  mysite = API('https://mysite.com/api', '~/mysite/config', profile="my_own_profile")
  role_description = session.api.describe_role(role)
  

Class API

Constructor

root

The URL of the site's API.

config_files

optional ([]) A str or list of str's. The config files to search for profiles.

index

optional (None) Your site's index. The index your site would provide. By default api_api gets the index from the site, As a site-provider, if you want to reduce traffic, you could provide a library with the index pre-baked.

headers

optional ({}) Any additional headers to provide to the site. In normal use, this is unnecessary, but when you develope your own site you may need to pretend to be talking to a particular host:

mydevsite = API('http://127.0.0.1:8000/api', headers={'host':'mysite.com'})

profile

optional ('default'). The profile to use for the default session.

Methods

API[index]

Get a value from the configured profile.

API()

Create a session.

key_id, key_secret

Use this key and secret for the session.

profile

Use this profile for the session.=None,

headers

Additional headers for HTTP calls to the site.

Class Session

The attributes of a Session are the applications with apis of the site.

Config Files

These are the settings recognised in config files:

access_key_id

The id of the access key.

access_key_secret

The secrte of the access key.

api_root

optional The root of the api, eg https://mysite.com/api. In normal use this would not be set, but when developing a website using api, you may need to redirect to your local, development host, eg http://127.0.0.1:8000/api.

api_host

optional The host to send to the api. In normal use this would not be set, but when developing a website using api, you may need to pretend you're talking to your real host, eg mysite.com

Example normal use:

joe_bloggs:
access_key_id = k-0123456789abcdef
access_key_secret = 0123456789012345678901234567890123456789

Example for connecting to your development site:

joe_bloggs_dev:
access_key_id = k-0123456789abcdef
access_key_secret = 0123456789012345678901234567890123456789
api_root = http://127.0.0.1:8000/api
api_host = mysite.com