Add an API

2026-05-04 15:04:03 +00:00 · 2019-09-18 20:48:08 +02:00
parent f22d5915ea
commit b07d9d167d
13 changed files with 408 additions and 10 deletions
--- a/doc/api/resources/giftcards.rst
+++ b/doc/api/resources/giftcards.rst
@@ -0,0 +1,181 @@
+.. _`rest-giftcards`:
+
+Gift cards
+==========
+
+Resource description
+--------------------
+
+The gift card resource contains the following public fields:
+
+.. rst-class:: rest-resource-table
+
+===================================== ========================== =======================================================
+Field                                 Type                       Description
+===================================== ========================== =======================================================
+id                                    integer                    Internal ID of the gift card
+secret                                string                     Gift card code (can not be modified later)
+value                                 money (string)             Current gift card value
+currency                              string                     Currency of the value (can not be modified later)
+===================================== ========================== =======================================================
+
+Endpoints
+---------
+
+.. http:get:: /api/v1/organizers/(organizer)/giftcards/
+
+   Returns a list of all gift cards issued by a given organizer.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /api/v1/organizers/bigevents/giftcards/ HTTP/1.1
+      Host: pretix.eu
+      Accept: application/json, text/javascript
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Vary: Accept
+      Content-Type: application/json
+
+      {
+        "count": 1,
+        "next": null,
+        "previous": null,
+        "results": [
+          {
+            "id": 1,
+            "secret": "HLBYVELFRC77NCQY",
+            "currency": "EUR",
+            "value": "13.37"
+          }
+        ]
+      }
+
+   :query integer page: The page number in case of a multi-page result set, default is 1
+   :param organizer: The ``slug`` field of the organizer to fetch
+   :statuscode 200: no error
+   :statuscode 401: Authentication failure
+   :statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
+
+.. http:get:: /api/v1/organizers/(organizer)/giftcards/(id)/
+
+   Returns information on one gift card, identified by its ID.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      GET /api/v1/organizers/bigevents/giftcards/1/ HTTP/1.1
+      Host: pretix.eu
+      Accept: application/json, text/javascript
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Vary: Accept
+      Content-Type: application/json
+
+      {
+        "id": 1,
+        "secret": "HLBYVELFRC77NCQY",
+        "currency": "EUR",
+        "value": "13.37"
+      }
+
+   :param organizer: The ``slug`` field of the organizer to fetch
+   :param id: The ``id`` field of the gift card to fetch
+   :statuscode 200: no error
+   :statuscode 401: Authentication failure
+   :statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
+
+.. http:post:: /api/v1/organizers/(organizer)/giftcards/
+
+   Creates a new gift card
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      POST /api/v1/organizers/bigevents/giftcards/ HTTP/1.1
+      Host: pretix.eu
+      Accept: application/json, text/javascript
+      Content-Type: application/json
+
+      {
+        "secret": "HLBYVELFRC77NCQY",
+        "currency": "EUR",
+        "value": "13.37"
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 201 Created
+      Vary: Accept
+      Content-Type: application/json
+
+      {
+        "id": 1,
+        "secret": "HLBYVELFRC77NCQY",
+        "currency": "EUR",
+        "value": "13.37"
+      }
+
+   :param organizer: The ``slug`` field of the organizer to create a gift card for
+   :statuscode 201: no error
+   :statuscode 400: The gift card could not be created due to invalid submitted data.
+   :statuscode 401: Authentication failure
+   :statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
+
+.. http:patch:: /api/v1/organizers/(organizer)/giftcards/(id)/
+
+   Update a gift card. You can also use ``PUT`` instead of ``PATCH``. With ``PUT``, you have to provide all fields of
+   the resource, other fields will be reset to default. With ``PATCH``, you only need to provide the fields that you
+   want to change.
+
+   You can change all fields of the resource except the ``id``, ``secret``, and ``currency`` fields. Be careful when
+   modifying the ``value`` field to avoid race conditions.
+
+   **Example request**:
+
+   .. sourcecode:: http
+
+      PATCH /api/v1/organizers/bigevents/giftcards/1/ HTTP/1.1
+      Host: pretix.eu
+      Accept: application/json, text/javascript
+      Content-Type: application/json
+      Content-Length: 94
+
+      {
+        "value": "14.00"
+      }
+
+   **Example response**:
+
+   .. sourcecode:: http
+
+      HTTP/1.1 200 OK
+      Vary: Accept
+      Content-Type: application/json
+
+      {
+        "id": 1,
+        "secret": "HLBYVELFRC77NCQY",
+        "currency": "EUR",
+        "value": "13.37"
+      }
+
+   :param organizer: The ``slug`` field of the organizer to modify
+   :param id: The ``id`` field of the gift card to modify
+   :statuscode 200: no error
+   :statuscode 400: The gift card could not be modified due to invalid submitted data
+   :statuscode 401: Authentication failure
+   :statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.