You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Eine prägnante Anleitung zu API-Benutzerfreundlichkeit, Auffindbarkeit und Konsistenz, die auf bewährten Designphilosophien und Benutzeranforderungen basiert.
4
-
5
-
**Ergebnisse**
6
-
7
-
* Besseres Verständnis der API-Designprinzipien
8
-
9
-
**So funktioniert**
10
-
**Schritte**
11
-
12
-
1.**Verbraucherorientiertes Design:** Beginnen Sie jeden APIOps-Zyklus mit der Erfassung der Benutzerziele und Fachbegriffe, damit APIs echte Probleme lösen können.
13
-
2.**Einheitliche Benennung und Verhalten:** Wenden Sie gemeinsame Konventionen für Ressourcen, Fehler und Formate an, um APIs vorhersehbar zu machen.
14
-
3.**Vertragsorientiert:** Erfassen Sie die Schnittstelle mit OpenAPI oder AsyncAPI vor dem Codieren, um Teams aufeinander abzustimmen und Automatisierung zu ermöglichen.
15
-
4.**Benutzerfreundlichkeit und Auffindbarkeit:** Stellen Sie klare Dokumentationen und Beispiele bereit, damit Entwickler schnell verstehen, wie die API zu verwenden ist.
16
-
5.**Sichere Iteration:** Entwickeln Sie Designs in kleinen, versionierten Schritten weiter, damit Änderungen keine bestehenden Verbraucher beeinträchtigen.
17
-
18
-
Tipp
19
-
20
-
* Passen Sie die API-Designprinzipien an Ihre Domäne an
21
-
* Verwenden Sie sie gemeinsam in verschiedenen Geschäfts- und Technikbereichen.
22
-
23
-
**API-Styleguide**
1
+
## API-Styleguide
24
2
25
3
Dieser Leitfaden enthält Best Practices und Standards für die Entwicklung und Implementierung von RESTful-APIs, um Sicherheit, Konsistenz, Benutzerfreundlichkeit und die Ausrichtung auf die Unternehmensziele zu gewährleisten. Er steht auch im Einklang mit der API-Audit-Checkliste.
4
+
26
5
---
27
6
28
-
**1\. Sicherheit und Datenschutz**
29
-
**HTTPS-Durchsetzung**
7
+
### 1\. Sicherheit und Datenschutz
8
+
9
+
#### HTTPS-Durchsetzung
30
10
31
11
* Alle APIs müssen HTTPS erzwingen, um Daten während der Übertragung zu verschlüsseln.
32
12
* Sensible Informationen (z. B. Tokens, Anmeldedaten, personenbezogene Daten) dürfen niemals in URLs oder Abfrageparametern übertragen werden. Verwenden Sie für solche Daten den Request Body.
33
13
34
-
**Rollenbasierte Zugriffskontrolle (RBAC)**
14
+
#### Rollenbasierte Zugriffskontrolle (RBAC)
35
15
36
16
* Implementieren Sie RBAC mithilfe von Identitätsanbietern und setzen Sie Berechtigungen innerhalb der API-Logik durch.
37
17
* Dokumentieren Sie rollenspezifische Zugriffskontrollen in der API-Dokumentation.
@@ -41,72 +21,75 @@ Dieser Leitfaden enthält Best Practices und Standards für die Entwicklung und
41
21
***Skalierung**: Dynamische Rollenprüfungen basierend auf API-Nutzern.
* Behebt die 10 größten Risiken der OWASP API Security, darunter:
47
27
***API6:2023 – Unrestricted Access to Sensitive Business Flows**: Beschränken Sie sensible Geschäftsabläufe durch geeignete Authentifizierung und Autorisierung.
48
28
***API7:2023 – Server-Side Request Forgery (SSRF)**: Validieren Sie Eingaben und bereinigen Sie Antworten, um SSRF-Schwachstellen zu verhindern.
49
29
***API2:2023 – Defekte Authentifizierung**: Stellen Sie robuste Authentifizierungsmechanismen (z. B. OAuth 2.0) sicher und validieren Sie Workflows für das Ablaufen von Tokens.
50
30
51
-
**Verschlüsselung im Ruhezustand**
31
+
#### Verschlüsselung im Ruhezustand
52
32
53
33
* Sensible Daten, die in Datenbanken gespeichert sind, müssen im Ruhezustand mit branchenüblichen Algorithmen verschlüsselt werden.
54
34
* Stellen Sie sicher, dass keine sensiblen Daten in Protokollen oder URLs erscheinen.
55
35
56
36
---
57
37
58
-
**2\. HTTP-Methoden**
59
-
**Standardmäßige Verwendung**
38
+
### 2\. HTTP-Methoden
39
+
40
+
#### Standardmäßige Verwendung
60
41
61
42
* Verwenden Sie HTTP-Methoden konsistent:
62
-
* GET: Daten abrufen, ohne den Serverstatus zu ändern.
63
-
* POST: Erstellen Sie neue Ressourcen oder lösen Sie serverseitige Vorgänge aus.
64
-
* PUT: Aktualisieren Sie vorhandene Ressourcen (verwenden Sie vollständige Ressourcen-Payloads).
65
-
* PATCH: Aktualisieren Sie eine vorhandene Ressource teilweise.
66
-
* DELETE: Entfernen einer Ressource.
43
+
*`GET`: Daten abrufen, ohne den Serverstatus zu ändern.
44
+
*`POST`: Erstellen Sie neue Ressourcen oder lösen Sie serverseitige Vorgänge aus.
45
+
*`PUT`: Aktualisieren Sie vorhandene Ressourcen (verwenden Sie vollständige Ressourcen-Payloads).
46
+
*`PATCH`: Aktualisieren Sie eine vorhandene Ressource teilweise.
47
+
*`DELETE`: Entfernen einer Ressource.
67
48
68
-
**Idempotenz**
49
+
#### Idempotenz
69
50
70
51
* Stellen Sie sicher, dass die Methoden PUT, PATCH und DELETE idempotent sind, d. h. dass mehrere identische Anfragen zum gleichen Ergebnis führen.
71
52
72
-
**Testen von HTTP-Methoden**
53
+
#### Testen von HTTP-Methoden
73
54
74
55
* Validieren Sie alle HTTP-Methoden durch Integrationstests, um die Übereinstimmung mit dem erwarteten Verhalten sicherzustellen.
75
56
76
57
---
77
58
78
-
**3\. Fehlerbehandlung und Antworten**
79
-
**Standardisiertes Fehlerformat**
59
+
### 3\. Fehlerbehandlung und Antworten
60
+
61
+
#### Standardisiertes Fehlerformat
80
62
81
63
* Alle APIs müssen Fehler in einem standardisierten Format zurückgeben. Beispiel:
82
64
83
-
`{`
84
-
`„error”: „invalid_request”,`
85
-
`"message": "Der Anfrage fehlt ein erforderlicher Parameter.",`
86
-
`„details”: [`
87
-
88
-
`„Der Parameter „user_id” ist erforderlich.”`
89
-
`]`
90
-
`}`
65
+
```
66
+
{
67
+
"error": "invalid_request",
68
+
"message": "The request is missing a required parameter.",
69
+
"details": [
70
+
"Parameter 'user_id' is required."
71
+
]
72
+
}
73
+
```
91
74
92
-
**Ausführliche Beschreibungen**
75
+
#### Ausführliche Beschreibungen
93
76
94
77
* Fügen Sie für Menschen lesbare Fehlermeldungen hinzu, um Entwicklern bei der Fehlerbehebung zu helfen.
95
78
* Stellen Sie sicher, dass Fehlercodes und Beschreibungen mit der OpenAPI-Spezifikation übereinstimmen.
96
79
97
-
**HTTP-Statuscodes**
80
+
#### HTTP-Statuscodes
98
81
99
82
* Verwenden Sie für jeden Vorgang die entsprechenden Statuscodes:
100
-
* 200 OK: GET-, PUT- oder PATCH-Vorgänge erfolgreich.
101
-
* 201 Erstellt: Erfolgreicher POST-Vorgang, der zu einer neuen Ressource führt.
102
-
* 204 Kein Inhalt: Erfolgreicher DELETE-Vorgang.
103
-
* 400 Bad Request: Ungültige Eingabe oder fehlende Parameter.
*`429 Too Many Requests`: Ratenbegrenzung überschritten.
108
91
109
-
**Testen von Fehlerszenarien**
92
+
#### Testen von Fehlerszenarien
110
93
111
94
* Überprüfen Sie alle Fehlerszenarien, um korrekte Antworten und aussagekräftige Fehlermeldungen sicherzustellen.
112
95
***Reifegrade**:
@@ -117,8 +100,9 @@ Dieser Leitfaden enthält Best Practices und Standards für die Entwicklung und
117
100
118
101
---
119
102
120
-
**4\. Dokumentation und Entwicklererfahrung**
121
-
**Interaktive Dokumentation**
103
+
### 4\. Dokumentation und Entwicklererfahrung
104
+
105
+
#### Interaktive Dokumentation
122
106
123
107
* Generieren Sie API-Dokumentation mithilfe der OpenAPI-Spezifikation (neueste unterstützte Version).
124
108
* Fügen Sie Beispiele für alle Endpunkte hinzu, um Anfrage-/Antwort-Workflows zu veranschaulichen.
@@ -128,77 +112,91 @@ Dieser Leitfaden enthält Best Practices und Standards für die Entwicklung und
128
112
***Skalierung**: Entwicklertools für API-Tests.
129
113
***Innovativ**: Integrierte Entwicklerumgebungen zum Testen.
130
114
131
-
**Abschnitt „Erste Schritte“**
115
+
#### Abschnitt „Erste Schritte“
132
116
133
117
* Fügen Sie einen Abschnitt „Erste Schritte“ in die Dokumentation ein, um neue Benutzer durch die Authentifizierung, gängige Arbeitsabläufe und das Testen von Endpunkten zu führen.
134
118
* Verwenden Sie die Vorlage für die Erste-Schritte-Anleitung als Referenz.
135
119
136
-
**Sandbox-Umgebung**
120
+
#### Sandbox-Umgebung
137
121
138
122
* Bieten Sie eine Sandbox-Umgebung an, die Produktionsschemata und Fehlercodes für Testzwecke widerspiegelt.
139
123
* Überprüfen Sie die Sandbox-Ausrichtung durch API-Audit-Tests.
140
124
141
125
---
142
126
143
-
**5\. Namenskonventionen und Standards**
144
-
**Benennung von Ressourcen**
127
+
### 5\. Namenskonventionen und Standards
128
+
129
+
#### Benennung von Ressourcen
145
130
146
-
* Verwenden Sie beschreibende, branchenübliche englische Begriffe für Ressourcennamen (z. B. Bücher, Benutzer, Ausleihen).
147
-
* Vermeiden Sie mehrdeutige Begriffe wie „Typ” oder „Status” ohne zusätzlichen Kontext.
131
+
* Verwenden Sie beschreibende, branchenübliche englische Begriffe für Ressourcennamen (z. B. `books`, `users`, `loans`).
132
+
* Vermeiden Sie mehrdeutige Begriffe wie `type` oder `status` ohne zusätzlichen Kontext.
148
133
149
-
**Benennen von Attributen**
134
+
#### Benennen von Attributen
150
135
151
-
* Verwenden Sie für Attributnamen camelCase (z. B. userId, bookTitle).
136
+
* Verwenden Sie für Attributnamen camelCase (z. B. `userId`, `bookTitle`).
152
137
* Vermeiden Sie Akronyme und Abkürzungen, um Klarheit zu gewährleisten.
153
138
* Überprüfen Sie die Namenskonventionen während der OpenAPI-Validierung.
154
139
155
140
---
156
141
157
-
**6\. Lokalisierung und Internationalisierung**
158
-
**Header akzeptieren**
142
+
### 6\. Lokalisierung und Internationalisierung
159
143
160
-
* Unterstützen Sie die Lokalisierung mithilfe des Accept-Language\-Headers für API-Antworten.
144
+
#### Accept Headers
145
+
146
+
* Unterstützen Sie die Lokalisierung mithilfe des `Accept-Language` -Headers für API-Antworten.
161
147
* Stellen Sie lokalisierte Zeichenfolgen bereit und stellen Sie sicher, dass alle Fehlermeldungen übersetzt werden können.
162
148
163
-
**Datums- und Zeitformate**
149
+
#### Datums- und Zeitformate
164
150
165
151
* Verwenden Sie das ISO 8601-Format für alle Datums- und Zeitfelder, einschließlich Zeitzonen.
166
152
167
-
**Testen der Lokalisierung**
153
+
```
154
+
"createdAt": "2024-12-21T10:00:00Z"
155
+
```
156
+
157
+
#### Testen der Lokalisierung
168
158
169
159
* Validieren Sie lokalisierte Antworten und Fehlermeldungen durch Funktionstests.
170
160
171
161
---
172
162
173
-
**7\. Versionierung und Abkündigung**
174
-
**Versionierungsstrategie**
163
+
### 7\. Versionierung und Abkündigung
164
+
165
+
#### Versionierungsstrategie
175
166
176
-
* Verwenden Sie semantische Versionsnummern (z. B. /v1, /v2), um wesentliche Änderungen zu kennzeichnen.
167
+
* Verwenden Sie semantische Versionsnummern (z. B. `/v1`, `/v2`), um wesentliche Änderungen zu kennzeichnen.
177
168
* Vermeiden Sie grundlegende Änderungen innerhalb einer Version. Kündigen Sie alte Endpunkte mit ausreichender Vorankündigung.
178
169
179
170
**Hinweise zur Abkündigung**
180
171
181
172
* Kommunizieren Sie Veraltungen über das Entwicklerportal und fügen Sie Header in API-Antworten ein:
0 commit comments