api.rst

API

Agora ciudadana exports a REST API with full access to the data model and user actions.

Format

Access to /api/v1/xxxx to use the API resources, using the corresponding HTTP methods (GET, POST, PUT, DELETE...).

Requests and answers may use any of the standard formats: xml, json or yaml. The format may be specified via "Accept" HTTP headers or with ?format=json (or xml or yaml) parameter in the URL.

Status reporting

API calls use the standard HTTP codes for status reporting (200 OK, 404 Not Found, 403 Forbidden, etc.). In case of error, the returned data may have fields with additional info (see each individual call for more explanations).

Authentication

The API accepts two modes of authentication:

Readonly unathenticated queries

Some read-only queries can be requested with no authentication mechanism at all. For example the listing of agoras supports this. This is useful and handy if you just want to request some generic information.

Session authentication

The session cookie used in the normal login is accepted and identifies the user that is using the API. This is useful mainly for the javascript embedded in the own Agora pages.

Token authentication

For access the API with an external application, you need the auth token. When you call the login API function, the user token is returned, and you must supply it in the Authorization header in all next HTTP calls:

# As a header
# Format is ''Authorization: ApiKey <username>:<api_key>''
Authorization: ApiKey daniel:204db7bcfafb2deb7506b89eb3b9b715b09905c8

Currently the user token is currently only accesible through administrators that can access to the django shell:

In [1]: from tastypie.models import ApiKey

In [2]: ApiKey.objects.get(user__username="user1")
Out[2]: <ApiKey: b133b30b2348d7ba8ac6cb63b7aefb382c0804d2 for user1>

Lists, Pagination and filtering

When a list of resources is needed, Agora API always paginates the results. One can set a specific offset and limit the number of items. Also some listings allow filtering by some fields, for example a list of users might filter by username.

Filter fields sometimes are said to support django field lookups. In this case if this happens when filtering by username, you can also do a more advanced filtering by filtering only usernames that start with a given string with username__startswith parameter. See the different django field lookups available in https://docs.djangoproject.com/en/dev/ref/models/querysets/

Resource: Agora

List Agoras

Retrieve an agora

Create new agora

Delete an agora

Modify agora

Execute an action

Retrieve agora members

List administrators

List membership requests

Retrieve agora admin membership requests

List active delegates

List all elections

List tallied elections

List open elections

List requested elections

List archived elections

List approved elections

Comments

Add comment

List members ----------

Resource: User

Get User settings

Put User settings

User register

User login

User logout

Check username is available

Reset Password

Disable current user

List current user agoras

List agoras of a given user

List elections this user can vote in

List of valid usernames

Resource: Search

This resource allows searches, using Haystack

Resource: Election

This resource represents an election

Retrieve an election

Modify election

List all votes

List cast votes

List delegated votes

List votes from delegates

Direct votes

List comments

Add comment

Execute an action

Resource: CastVote

Represents a vote in an election.

Retrieve a vote

Resource: DelegateElectionCount

This resource stores how many delegated votes an election delegate got in a given election. These resources are created when an election is tallied.

List

Retrieve