api.rst 5.24 KB
Newer Older
Nicolas Joyard's avatar
Nicolas Joyard committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
API Documentation
~~~~~~~~~~~~~~~~~

Memopol publishes its data with a read-only REST API using `Django REST
Framework <http://www.django-rest-framework.org/>`_.  The API is browseable and
partially self-documented, from the ``/api`` URL.

The goal of this documentation is to plug the holes in the
automatically-generated documentation.

Overview
========

The API homepage resides at the ``/api/`` URL. Each model is accessible from two
URLs:

* ``/api/<model>/`` for a (filterable) list of objects
* ``/api/<model>/<pk>/`` to get a detailed view of a specific object

When accessing the API from a web browser, data should be displayed in a
user-friendly paginated interface, and relation fields are links to the
corresponding API URLs (if that's not the case, you can force it by appending
``format=api`` to the querystring).  To get raw JSON data instead, either pass
an ``Accept: application/json`` request header or append ``format=json`` to the
querystring.

Object lists may be filtered using ``field=value`` in the querystring ; related
fields may be used in filters with double underscores (for example
``representative__name=John``).  Alternative operators may be available for
some fields (for example ``score__gte=100``), amongst which:

* ``lte``: matches values that are lower than or equal to the specified value
* ``gte``: matches values greater than equal to or the specified value
* ``icontains``: matches values that contain the specified value, ignoring case

Note that fields that are made available for filtering depend on each model;
the same goes for alternative operators (by default only exact match is
available).

Finally, note that this documentation does not show the data schema.  Feel free
to browse the API yourself to find out how data is published.

Representatives API
===================

This API provides views on representatives and mandates.

Representatives
---------------

The ``/api/representatives/[<pk>/]`` endpoints give access to representatives.
The following fields are available for filtering:

* ``active``: True or False
* ``slug`` (alt.: icontains)
* ``id``
* ``remote_id``
* ``first_name``
* ``last_name`` (alt.: icontains)
* ``gender``: M or F
* ``birth_place``
* ``birth_date`` (alt.: gte, lte)
* ``search``: searches in the ``first_name``, ``last_name`` and ``slug`` fields

Mandates
--------

The ``/api/mandates/[<pk>/]`` endpoints give access to mandates. The following
fields are available for filtering:

* ``id``
* ``group__name`` (alt.: icontains)
* ``group__abbreviation``
* ``search``: searches in the ``group__name`` and ``group_abbreviation`` fields

Constituency
------------

The ``/api/constituencies/[<pk>/]`` endpoints give access to constituencies.

Groups
------

The ``/api/groups/[<pk>/]`` endpoints give access to groups.

Representatives-votes API
=========================

This API provides views on dossiers, proposals and votes.

Dossiers
--------

The ``/api/dossiers/[<pk>/]`` endpoints give access to dossiers. The following
fields are available for filtering:

* ``fingerprint``
* ``title`` (alt.: icontains)
* ``reference`` (alt.: icontains)
* ``search``: searches in the ``fingerprint``, ``title``, ``reference``,
  ``text`` and ``proposals__title`` fields

Proposals
---------

The ``/api/proposals/[<pk>/]`` endpoints give access to proposals. The following
fields are available for filtering:

* ``fingerprint``
* ``dossier__fingerprint``
* ``title`` (alt.: icontains)
* ``description`` (alt.: icontains)
* ``reference`` (alt.: icontains)
* ``datetime`` (alt.: gte, lte)
* ``kind``
* ``search``: searches in the ``fingerprint``, ``title``,
  ``dossier__fingerprint``, ``dossier__title`` and ``dossier__reference`` fields

Votes
-----

The ``/api/votes/[<pk>/]`` endpoints give access to votes. The following fields
are available for filtering:

* ``proposal__fingerprint``
* ``position``
* ``representative_name`` (alt.: icontains)
* ``representative``


Memopol API
===========

This API provides views on recommendations and representative scores.

Recommendations
---------------

The ``/api/recommendations/[<pk>/]`` endpoints give access to recommendations.
The following fields are available for filtering:

* ``id``
* ``recommendation``
* ``title`` (alt.: icontains)
* ``description`` (alt.: icontains)
* ``weight`` (alt.: gte, lte)
* ``search``: searches in the ``title`` and ``description`` fields

149 150
Vote Scores
-----------
Nicolas Joyard's avatar
Nicolas Joyard committed
151

152 153 154
The ``/api/vote_scores/[<pk>/]`` endpoints give access to scored votes; that is,
representative votes with their contribution to the representative score. Only
votes that match a recommendation are visible using this endpoint.  The
Nicolas Joyard's avatar
Nicolas Joyard committed
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180
following fields are available for filtering:

* ``representative``
* ``proposal``
* ``proposal__dossier``

Dossier Scores
--------------

The ``/api/dossier_scores/[<pk>/]`` endpoints give access to dossier scores;
that is, the contribution of each dossier on a representative score. Only
dossiers with recommendations are visible using this endpoint.  The following
fields are available for filtering:

* ``dossier``
* ``representative``
* ``score`` (alt.: gte, lte)

Representative scores
---------------------

The ``/api/scores/[<pk>/]`` endpoints give access to total scores for each
representative. The following fields are available for filtering:

* ``representative``
* ``score`` (alt.: gte, lte)