rattic_api

# API Usage

RatticDB include an API that you an use to programatically acces the data you have stored. Currently the API only supports read access for credential, however we expect this to change at time progresses.

## Authentication

To authenticate to RatticDB you can choose to use either session authentication, or API Key authentication. Sessions keys require a user to have logged in with their username, password and if configured their one time pad device. API keys on the other hand are static values that are designed for systems that may not have interactive access.

To use the session based authentication simply use your browser to log into RatticDB and then browse to the API endpoints. Because the Accept header cannot usually be controlled in most web browsers you need to provide a hint as to the format of the request via the query string. So for example if you wanted to hit the `/api/v1/cred/1/` endpoint and get JSON data returned you would append `?format=json` which would make the URL be `/api/v1/cred/1/?format=json`. This method is designed to be convenient for use in a browser, for example with a browser extension, or to debug the API.

The API key authentication method requires the user to have logged in, and retrieved an API Key. This can be done on the profile page. Authenticating a request using an API simply requires the addition of an `Authorization` header. This header should contain the `ApiKey` keyword, a space, the username of the user to log in as, a colon and finally the secret part of the API key. For example the user `daniel` with an API secret key of `1234567890abcdef` would send the following HTTP header `Authorization: ApiKey daniel:1234567890abcdef`. Note that if using this authentication method you should also change the `Accept` header to indicate the mime type of the data you would like returned, such as `application/json`. If you don't do this then you need to specify the type in the query string the same way you would with session authentication.

## Endpoints

RatticDB's version 1 API uses TastyPie for its API. This means the documentation at `http://django-tastypie.readthedocs.org/en/latest/interacting.html` mostly applies. This documentation goes into much more detail, so we will keep the documentation here as simple as possible.

### GET /api/v1/cred/

Returns a list of credentials. Passwords are only included when a single cred is requested (see below).

Parameters:

* limit: number of objects (default 20)
* offset: begin fetching objects at this position (default 0)

### GET /api/v1/cred/<cred_id>

Returns details for a credential, including the password.