Refs #314 -- Read-only REST API (#513)

* initial commit * API auth * Hierarchical URLs * Add session auth * Strong hierarchy * Add filters * Add i18n fields, questions * More viewsets and serializers * Ticket download * Add OrderPosition serializer * View-level permissions * More tests * More tests * Add basic API docs * Add REST API to docs frontpage * Tests for order endpoints * Add invoice tests * Voucher and waitinglist tests * Doc draft * order docs * Docs on all viewsets * Disable DRF docs, style sphinx, style browsable API * Fix tests * deprecated imports * Test foo * Attendee names * Fix migration problems * Remove browsable API, plugin integration * Doc fixes
2017-06-19 11:16:04 +02:00
parent 6df3a7d4b5
commit b2d4bea1d0
71 changed files with 4213 additions and 59 deletions
@@ -96,3 +96,52 @@ correctly ensure that:
 * The ``request.event`` attribute contains the correct ``Event`` object
 * The ``request.organizer`` attribute contains the correct ``Organizer`` object
 * The locale is set correctly
+
+REST API viewsets
+-----------------
+
+Our REST API is built upon `Django REST Framework`_ (DRF). DRF has two important concepts that are different from
+standard Django request handling: There are `ViewSets`_ to group related views in a single class and `Routers`_ to
+automatically build URL configurations from them.
+
+To integrate a custom viewset with pretix' REST API, you can just register with one of our routers within the
+``urls.py`` module of your plugin::
+
+
+    from pretix.api.urls import event_router, router, orga_router
+
+    router.register('global_viewset', MyViewSet)
+    orga_router.register('orga_level_viewset', MyViewSet)
+    event_router.register('event_level_viewset', MyViewSet)
+
+Routes registered with ``router`` are inserted into the global API space at ``/api/v1/``. Routes registered with
+``orga_router`` will be included at ``/api/v1/organizers/(organizer)/`` and routes registered with ``event_router``
+will be included at ``/api/v1/organizers/(organizer)/events/(event)/``.
+
+In case of ``orga_router`` and ``event_router``, permission checking is done for you similarly as with custom views
+in the control panel. However, you need to make sure on your own only to return the correct subset of data! ``request
+.event`` and ``request.organizer`` are available as usual.
+
+To require a special permission like ``can_view_orders``, you do not need to inherit from a special ViewSet base
+class, you can just set the ``permission`` attribute on your viewset::
+
+    class MyViewSet(ModelViewSet):
+        permission = 'can_view_orders'
+        ...
+
+If you want to check the permission only for some methods of your viewset, you have to do it yourself. Note here that
+API authentications can be done via user sessions or API tokens and you should therefore check something like the
+following::
+
+
+    perm_holder = (request.auth if isinstance(request.auth, TeamAPIToken) else request.user)
+    if perm_holder.has_event_permission(request.event.organizer, request.event, 'can_view_orders'):
+        ...
+
+
+.. warning:: It is important that you do this in the ``yourplugin.urls`` module, otherwise pretix will not find your
+             routes early enough during system startup.
+
+.. _Django REST Framework: http://www.django-rest-framework.org/
+.. _ViewSets: http://www.django-rest-framework.org/api-guide/viewsets/
+.. _Routers: http://www.django-rest-framework.org/api-guide/routers/