.. _api_views:

.. index::
    single: APIView
    single: REST API
    single: HTTP-Methoden
    single: DRF
    single: GET
    single: POST
    single: JSONResponse

Eine erste API-View einrichten
*******************************

Wir starten nun mit dem Aufbau unserer eigenen REST-API. Als Einstieg verwenden wir **APIView** – die grundlegende Klasse des Django REST Frameworks (DRF). Sie erlaubt uns die volle Kontrolle über das Verhalten unserer API-Endpunkte und eignet sich hervorragend, um die Funktionsweise von HTTP-Methoden wie ``GET`` oder ``POST`` zu verstehen.

In diesem Kapitel zeigen wir, wie man mit einer einfachen ``APIView`` einen Überblick über vorhandene Events abruft und neue Events erstellen kann – ganz ohne ViewSets oder Generics.


Ziel dieser View
================

Die View soll Folgendes leisten:

- Bei einem ``GET``-Request: Alle vorhandenen Events als JSON anzeigen
- Bei einem ``POST``-Request: Ein neues Event anlegen (minimal)

**Hinweis:** Wir verwenden in diesem ersten Schritt bewusst nur ein Minimum an Feldern, z. B. ``name``, ``slug``, ``date`` und ``category``.


Serializer vorbereiten
======================

Um die Daten des Modells ``Event`` in JSON umzuwandeln und umgekehrt, benötigen wir einen sogenannten **Serializer**.

Wir erstellen in ``event_manager/events/api/serializers.py`` einen sehr einfachen Serializer für das Modell ``Event``:

.. code-block:: python

    from rest_framework import serializers
    from events.models import Event

    class EventSerializer(serializers.ModelSerializer):
        class Meta:
            model = Event
            fields = ["id", "name", "slug", "date", "category"]


APIView erstellen
=================

Die View legen wir in der Datei ``event_manager/events/api/views.py`` an:

.. code-block:: python

    from rest_framework.views import APIView
    from rest_framework.response import Response
    from rest_framework import status
    from events.models import Event
    from .serializers import EventSerializer

    class EventListCreateAPIView(APIView):
        def get(self, request):
            events = Event.objects.all()
            serializer = EventSerializer(events, many=True)
            return Response(serializer.data)

        def post(self, request):
            serializer = EventSerializer(data=request.data)
            if serializer.is_valid():
                serializer.save(author=request.user)
                return Response(serializer.data, status=status.HTTP_201_CREATED)
            return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

.. tip::

    ``APIView`` ist die direkteste Art, eine API-Logik mit DRF zu schreiben. Sie bietet volle Kontrolle – erfordert aber auch, dass wir die Methoden ``get()``, ``post()`` usw. explizit selbst definieren.


URL-Routing
===========

Um die View unter einer URL erreichbar zu machen, registrieren wir sie in ``event_manager/events/api/urls.py``:

.. code-block:: python

    from django.urls import path
    from .views import EventListCreateAPIView

    urlpatterns = [
        path("events/", EventListCreateAPIView.as_view(), name="event-list-create"),
    ]

Und binden diese URLs in ``event_manager/urls.py`` ein:

.. code-block:: python

    from django.urls import path, include

    urlpatterns = [
        path("api/", include("events.api.urls")),
    ]

Wir können nun mit ``GET`` und ``POST`` unter ``/api/events/`` auf unsere API zugreifen.


Die API ausprobieren
====================

Wir testen die API mit einem Tool wie **HTTPie**, **curl** oder **Postman**.

GET an ``/api/events/``:

.. code-block:: shell

    http GET http://localhost:8000/api/events/

POST an ``/api/events/`` (Beispiel):

.. code-block:: shell

    http POST http://localhost:8000/api/events/ \
        name="Klettern" \
        slug="klettern" \
        date="2025-09-01T12:00:00Z" \
        category=1

.. admonition:: Good Practice

    In echten Projekten solltest du Validierung, Rechte (Permissions) und Fehlerbehandlung noch robuster gestalten. Für den Einstieg verzichten wir darauf, um die Grundidee besser zu verstehen.


Was haben wir gelernt?
======================

- Wie man mit ``APIView`` eine einfache API erstellt
- Wie man Daten mit einem Serializer in JSON umwandelt
- Wie ``GET`` und ``POST`` verarbeitet werden
- Wie die ersten API-Endpunkte in DRF funktionieren

Im nächsten Schritt erweitern wir diese API um weitere Methoden und führen **Permissions**, **Validierung** und später auch **Serializers mit verschachtelten Beziehungen** ein.


**Weiterführende Links:**

* https://www.django-rest-framework.org/api-guide/views/
* https://www.django-rest-framework.org/tutorial/quickstart/