API-Design
1. Grundprinzipien des API-Designs
Ziel: Schaffung einer klaren, konsistenten und gut dokumentierten Schnittstelle, die einfach zu verwenden und zu warten ist.
| Prinzip | Beschreibung | Beispiel |
|---|---|---|
| Klarheit | Die API sollte intuitiv und leicht verständlich sein. | Verwendung von sprechenden Namen für Endpunkte wie /getBooks statt /gb. |
| Konsistenz | Einheitliches Design und Namenskonventionen über die gesamte API hinweg. | Einhalten von RESTful-Prinzipien wie konsistente Nutzung von HTTP-Methoden (GET, POST, PUT, DELETE). |
| Dokumentation | Ausführliche und leicht zugängliche Dokumentation der API-Funktionen und Endpunkte. | Einsatz von Tools wie Swagger zur automatischen Generierung von API-Dokumentationen. |
| Sicherheit | Implementierung von Authentifizierungs- und Autorisierungsmechanismen. | Nutzung von OAuth2 für den sicheren Zugang zu geschützten Endpunkten. |
Beispiel eines klaren und konsistenten API-Designs:
GET /books - Listet alle Bücher auf
POST /books - Fügt ein neues Buch hinzu
GET /books/{id} - Ruft ein Buch anhand der ID ab
PUT /books/{id} - Aktualisiert ein Buch anhand der ID
DELETE /books/{id} - Löscht ein Buch anhand der ID
2. RESTful API-Design
Ziel: Erstellung von APIs, die den Prinzipien der REST-Architektur (Representational State Transfer) folgen.
Grundlagen von RESTful APIs:
| Prinzip | Beschreibung | Beispiel |
|---|---|---|
| Ressourcenzentriert | Jede Ressource wird durch eine eindeutige URL identifiziert. | /books, /users |
| Zustandslosigkeit | Jeder API-Aufruf ist unabhängig und enthält alle notwendigen Informationen. | Übermittlung von Authentifizierungsinformationen bei jeder Anfrage. |
| HTTP-Methoden | Verwendung von HTTP-Methoden zur Durchführung von CRUD-Operationen (Create, Read, Update, Delete). | GET, POST, PUT, DELETE |
| Selbstbeschreibende Nachrichten | Die Nachrichten (Requests/Responses) enthalten alle Informationen, die der Client/Server benötigt. | Nutzung von HTTP-Headern zur Übermittlung von Metadaten. |
Beispiel eines RESTful API-Designs:
GET /books - Listet alle Bücher auf
POST /books - Fügt ein neues Buch hinzu
GET /books/{id} - Ruft ein Buch anhand der ID ab
PUT /books/{id} - Aktualisiert ein Buch anhand der ID
DELETE /books/{id} - Löscht ein Buch anhand der ID
Beispiel einer RESTful API-Implementierung in Python (Flask):
from flask import Flask, request, jsonify
app = Flask(__name__)
# Beispiel-Daten
books = [
{"id": 1, "title": "Programmieren 101", "author": "Max Mustermann"},
{"id": 2, "title": "Datenbanken", "author": "Jane Doe"}
]
@app.route('/books', methods=['GET'])
def get_books():
# Gibt alle Bücher zurück
return jsonify(books)
@app.route('/books/<int:id>', methods=['GET'])
def get_book(id):
# Sucht ein Buch anhand der ID
book = next((book for book in books if book["id"] == id), None)
return jsonify(book) if book else ("", 404)
@app.route('/books', methods=['POST'])
def add_book():
# Fügt ein neues Buch hinzu
new_book = request.get_json()
books.append(new_book)
return jsonify(new_book), 201
@app.route('/books/<int:id>', methods=['PUT'])
def update_book(id):
# Aktualisiert ein Buch anhand der ID
book = next((book for book in books if book["id"] == id), None)
if book:
data = request.get_json()
book.update(data)
return jsonify(book)
return ("", 404)
@app.route('/books/<int:id>', methods=['DELETE'])
def delete_book(id):
# Löscht ein Buch anhand der ID
global books
books = [book for book in books if book["id"] != id]
return ("", 204)
if __name__ == '__main__':
app.run(debug=True)
3. API-Dokumentation
Ziel: Bereitstellung einer klaren und umfassenden Dokumentation, die die Nutzung der API erleichtert.
| Tool | Beschreibung | Beispiel |
|---|---|---|
| Swagger/OpenAPI | Ein Framework zur Erstellung und Visualisierung von API-Dokumentationen. | Nutzung von Swagger zur Generierung einer interaktiven Dokumentation für die Bibliotheks-API. |
| Postman | Ein Tool zum Testen von APIs und zur Dokumentation der API-Requests und -Responses. | Erstellung von Beispielanfragen und -antworten in Postman. |
| Redoc | Ein Tool zur Generierung von ansprechenden und benutzerfreundlichen API-Dokumentationen. | Einsatz von Redoc zur Darstellung der API-Dokumentation. |
Beispiel einer Swagger-API-Dokumentation:
openapi: 3.0.0
info:
title: Bibliotheks-API
version: 1.0.0
paths:
/books:
get:
summary: Listet alle Bücher auf
responses:
'200':
description: Erfolgreiche Antwort
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Book'
post:
summary: Fügt ein neues Buch hinzu
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
responses:
'201':
description: Buch erfolgreich hinzugefügt
/books/{id}:
get:
summary: Ruft ein Buch anhand der ID ab
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Erfolgreiche Antwort
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
put:
summary: Aktualisiert ein Buch anhand der ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Book'
responses:
'200':
description: Buch erfolgreich aktualisiert
delete:
summary: Löscht ein Buch anhand der ID
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'204':
description: Buch erfolgreich gelöscht
components:
schemas:
Book:
type: object
properties:
id:
type: integer
title:
type: string
author:
type: string
isbn:
type: string
publicationYear:
type: integer
4. Sicherheit
Ziel: Schutz der API vor unbefugtem Zugriff und Datenmissbrauch.
Beispiel einer sicheren API-Implementierung:
from flask import Flask, request, jsonify
from flask_httpauth import HTTPBasicAuth
app = Flask(__name__)
auth = HTTPBasicAuth()
# Benutzername und Passwort für die Authentifizierung
users = {
"admin": "password"
}
@auth.verify_password
def verify_password(username, password):
# Überprüfen des Benutzernamens und Passworts
if username in users and users[username] == password:
return username
@app.route('/books', methods=['GET'])
@auth.login_required
def get_books():
# Gibt alle Bücher zurück, nur für authentifizierte Benutzer
return jsonify(books)
# Weitere API-Endpunkte...
if __name__ == '__main__':
app.run(debug=True, ssl_context='adhoc')