Add plugin documentation

doc/plugins/pretixdroid.rst

@@ -0,0 +1,100 @@
+pretixdroid HTTP API
+====================
+
+The pretixdroid plugin provides a HTTP API that the `pretixdroid Android app`_
+uses to communicate with the pretix server.
+
+.. http:post:: /pretixdroid/api/(organizer)/(event)/redeem/
+
+   Redeems a ticket, i.e. checks the user in.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /pretixdroid/api/demoorga/democon/redeem/?key=ABCDEF HTTP/1.1
+      Host: demo.pretix.eu
+      Accept: application/json, text/javascript
+      Content-Type: application/x-www-form-urlencoded
+
+      secret=az9u4mymhqktrbupmwkvv6xmgds5dk3
+
+   **Example successful response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/json
+
+      {
+        'status': 'ok'
+        'version': 2
+      }
+
+   **Example error response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/json
+
+      {
+        'status': 'error',
+        'reason': 'already_redeemed',
+        'version': 2
+      }
+
+   Possible error reasons:
+
+   * ``unpaid`` - Ticket is not paid for or has been refunded
+   * ``already_redeemed`` - Ticket already has been redeemed
+   * ``unknown_ticket`` - Secret does not match a ticket in the database
+
+   :query key: Secret API key
+         :statuscode 200: Valid request
+         :statuscode 404: Unknown organizer or event
+         :statuscode 403: Invalid authorization key
+
+.. http:get:: /pretixdroid/api/(organizer)/(event)/search/
+
+   Searches for a ticket.
+   At most 25 results will be returned. **Queries with less than 4 characters will always return an empty result set.**
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /pretixdroid/api/demoorga/democon/search/?key=ABCDEF&query=Peter HTTP/1.1
+      Host: demo.pretix.eu
+      Accept: application/json, text/javascript
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Content-Type: text/json
+
+      {
+        'results': [
+          {
+            'secret': 'az9u4mymhqktrbupmwkvv6xmgds5dk3',
+            'order': 'ABCE6',
+            'item': 'Standard ticket',
+            'variation': null,
+            'attendee_name': 'Peter Higgs',
+            'redeemed': false,
+            'paid': true
+          },
+          ...
+        ],
+        'version': 2
+      }
+
+   :query query: Search query
+   :query key: Secret API key
+   :statuscode 200: Valid request
+   :statuscode 404: Unknown organizer or event
+   :statuscode 403: Invalid authorization key
+
+.. _pretixdroid Android app: https://github.com/pretix/pretixdroid