# JSON APIs und REST-Dienste

Ein umfassender Leitfaden zur Entwicklung und Nutzung von JSON-basierten REST-APIs.

Einführung in REST-APIs

REST (Representational State Transfer) ist ein Architekturstil für verteilte Systeme. JSON ist das bevorzugte Datenformat für REST-APIs.

Grundprinzipien

Zustandslos - Jede Anfrage ist unabhängig
Client-Server - Trennung von Zuständigkeiten
Cachebar - Antworten können gecacht werden
Einheitliche Schnittstelle - Standardisierte Interaktion

HTTP-Methoden

GET - Daten abrufen

GET /api/benutzer/123 HTTP/1.1 Host: api.example.com

Accept: application/json

Antwort:

{ "id": 123, "name": "Max Mustermann", "email": "max@example.de", "aktiv": true

}

POST - Neue Ressource erstellen

POST /api/benutzer HTTP/1.1 Host: api.example.com Content-Type: application/json { "name": "Anna Schmidt", "email": "anna@example.de"

}

Antwort (201 Created):

{ "id": 124, "name": "Anna Schmidt", "email": "anna@example.de", "erstellt": "2026-01-26T12:00:00Z"

}

PUT - Ressource aktualisieren

PUT /api/benutzer/123 HTTP/1.1 Host: api.example.com Content-Type: application/json { "name": "Max Mustermann", "email": "max.neu@example.de", "aktiv": true

}

PATCH - Teilweise aktualisieren

PATCH /api/benutzer/123 HTTP/1.1 Host: api.example.com Content-Type: application/json { "email": "max.neu@example.de"

}

DELETE - Ressource löschen

DELETE /api/benutzer/123 HTTP/1.1

Host: api.example.com

Antwort (204 No Content)

API-Response-Struktur

Erfolgreiche Antwort

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "Max Mustermann"
  },
  "message": "Benutzer erfolgreich abgerufen"
}

Fehlerantwort

{
  "status": "error",
  "error": {
    "code": "NOT_FOUND",
    "message": "Benutzer nicht gefunden",
    "details": {
      "userId": 999
    }
  }
}

Paginierte Liste

{
  "data": [
    {"id": 1, "name": "Max"},
    {"id": 2, "name": "Anna"}
  ],
  "pagination": {
    "seite": 1,
    "proSeite": 10,
    "gesamt": 100,
    "seiten": 10
  },
  "links": {
    "self": "/api/benutzer?seite=1",
    "next": "/api/benutzer?seite=2",
    "last": "/api/benutzer?seite=10"
  }
}

Authentifizierung

Bearer Token

GET /api/benutzer/123 HTTP/1.1 Host: api.example.com

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key

GET /api/daten HTTP/1.1 Host: api.example.com

X-API-Key: sk_live_1234567890

JavaScript Beispiele

Fetch API

// GET-Request
async function holeBenutzer(id) {
  const response = await fetch(https://api.example.com/benutzer/\\${id}, {
    headers: {
      'Accept': 'application/json'
    }
  });

  if (!response.ok) {
    throw new Error(HTTP \\${response.status});
  }

  return await response.json();
}

// POST-Request
async function erstelleBenutzer(daten) {
  const response = await fetch('https://api.example.com/benutzer', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify(daten)
  });

  return await response.json();
}

Mit axios

import axios from 'axios';

// Basis-Konfiguration
const api = axios.create({
  baseURL: 'https://api.example.com',
  headers: {
    'Content-Type': 'application/json'
  }
});

// GET
const benutzer = await api.get('/benutzer/123');
console.log(benutzer.data);

// POST
const neu = await api.post('/benutzer', {
  name: 'Max',
  email: 'max@example.de'
});

Python Beispiele

Mit requests

import requests

# GET
response = requests.get('https://api.example.com/benutzer/123')
if response.status_code == 200:
    benutzer = response.json()
    print(benutzer['name'])

# POST
daten = {
    'name': 'Max Mustermann',
    'email': 'max@example.de'
}

response = requests.post(
    'https://api.example.com/benutzer',
    json=daten,
    headers={'Authorization': f'Bearer {token}'}
)

neuer_benutzer = response.json()

Node.js API Server

Express.js Beispiel

const express = require('express');
const app = express();

app.use(express.json());

// GET /api/benutzer
app.get('/api/benutzer', (req, res) => {
  res.json({
    status: 'success',
    data: benutzerListe
  });
});

// GET /api/benutzer/:id
app.get('/api/benutzer/:id', (req, res) => {
  const benutzer = findeBenutzer(req.params.id);

  if (!benutzer) {
    return res.status(404).json({
      status: 'error',
      error: {
        code: 'NOT_FOUND',
        message: 'Benutzer nicht gefunden'
      }
    });
  }

  res.json({
    status: 'success',
    data: benutzer
  });
});

// POST /api/benutzer
app.post('/api/benutzer', (req, res) => {
  const neuerBenutzer = erstelleBenutzer(req.body);

  res.status(201).json({
    status: 'success',
    data: neuerBenutzer
  });
});

app.listen(3000);

Best Practices

1. Versionierung

https://api.example.com/v1/benutzer

https://api.example.com/v2/benutzer

2. Konsistente Namenskonvention

{
  "benutzerId": 123,
  "erstelltAm": "2026-01-26",
  "istAktiv": true
}

3. HTTP-Status-Codes richtig verwenden

200 OK - Erfolgreiche GET/PUT/PATCH
201 Created - Erfolgreiche POST
204 No Content - Erfolgreiche DELETE
400 Bad Request - Ungültige Anfrage
401 Unauthorized - Nicht authentifiziert
403 Forbidden - Keine Berechtigung
404 Not Found - Ressource nicht gefunden
500 Internal Server Error - Serverfehler

4. Rate Limiting

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Zu viele Anfragen"
  },
  "retryAfter": 60
}

5. CORS richtig konfigurieren

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'GET,POST,PUT,DELETE');
  res.header('Access-Control-Allow-Headers', 'Content-Type,Authorization');
  next();
});

Fehlerbehandlung

Client-seitig

async function apiRequest(url, options) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error.message);
    }

    return await response.json();
  } catch (error) {
    console.error('API-Fehler:', error);
    throw error;
  }
}

Server-seitig

app.use((err, req, res, next) => {
  console.error(err.stack);

  res.status(err.status || 500).json({
    status: 'error',
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message: err.message || 'Interner Serverfehler'
    }
  });
});

Zusammenfassung

JSON und REST sind perfekt für moderne APIs:

✅ Standardisiert

✅ Einfach zu verwenden

✅ Sprachunabhängig

✅ Weit verbreitet

JSON APIs und REST-Dienste: Vollständiger Entwickler-Leitfaden

Big JSON Team