#8 initial version of chapter 4

isaqb-org · Nov 20, 2024 · 9caa8bb · 9caa8bb
1 parent 0d59d72
commit 9caa8bb
Show file tree

Hide file tree

Showing 5 changed files with 39 additions and 60 deletions.
diff --git a/docs/04-api-design/00-structure.adoc b/docs/04-api-design/00-structure.adoc
@@ -3,11 +3,11 @@
 // ====================================================
 
 // tag::DE[]
-== Viertes Modul, das ist sein Titel
+== API Design
 // end::DE[]
 
 // tag::EN[]
-== Fourth Module, This is its Title
+== API Design
 // end::EN[]
 
 include::01-duration-terms.adoc[{include_configuration}]

diff --git a/docs/04-api-design/01-duration-terms.adoc b/docs/04-api-design/01-duration-terms.adoc
@@ -1,29 +1,19 @@
 // tag::DE[]
 |===
-| Dauer: XXX Min. | Übungszeit: XXX Min.
+| Dauer: 90 Min. | Übungszeit: 30 Min.
 |===
 
 === Begriffe und Konzepte
-Begriff 1, Begriff 2, Begriff 3
 
+Design von API-Schnittstellen, API First, konsumentengetriebenes API-Design, Postel's Law, Forward und Backward Compatibility, Versionierung und Lebenszyklus von API Produkten, JSON:API, API Design Style Guides
 
 // end::DE[]
 
 // tag::EN[]
 |===
-| Duration: XXX min | Practice time: XXX min
+| Duration: 90 min | Practice time: 30 min
 |===
 
 === Terms and Principles
 Term 1, Term 2, Term 3
 // end::EN[]
-
-[NOTE]
-====
-Überschrift in 00-structure.adoc ersetzen
-====
-
-[NOTE]
-====
-Sinnvolle Zeiten für Dauer und Übungszeit eintragen, vernünftige Begriffe aufzählen.
-====
diff --git a/docs/04-api-design/02-learning-goals.adoc b/docs/04-api-design/02-learning-goals.adoc
@@ -2,19 +2,41 @@
 
 // tag::DE[]
 [[LZ-4-1]]
-==== LZ 4-1: Dies ist das erste Lernziel in Kapitel 4, das mit xyz
+==== LZ 4-1: Bedeutung von API Design verstehen
 
-Hier wird beschrieben, was Teilnehmer:innen in diesem Lernziel lernen sollen. Das kann in Prosa-Text
-in ganzen Sätzen oder in Aufzählungen mit Unterpunkten erfolgen. Dabei kann auch unterschieden werden,
-wie wichtig einzelne Aspekte des Lernziels sind. Es kann hier bereits auf Literatur verwiesen werden.
+Teilnehmer:innen verstehen, weshalb ein gewissenhaftes Design von API-Schnittstellen von großer Bedeutung ist und welchen Einfluss dies auf die Nutzbarkeit, Wartung, Weiterentwicklung und Verbreitung der Schnittstelle haben wird.
 
-* Erstes Teilziel
-* Zweites Unterthema
-* Dritter Aspekt
 
 [[LZ-4-2]]
-==== LZ 4-2: Hier ist ein zweites Lernziel in diesem Kapitel
-tbd.
+==== LZ 4-2: API Design als "Outside-in" Ansatz anwenden
+
+Zu den wichtigsten Zielen von APIs zählt die effiziente Anbindung von Konsumenten an die Schnittstelle des Betreibers.
+Das Design sollte auf die Anforderungen der Konsumenten fokussiert sein und nicht entlang eventuell bestehender Systeme, Use Cases oder Datenbanken. Teilnehmer:innen kennen und verstehen die Ansätze von API First und konsumentengetriebenem API-Design.
+
+[[LZ-4-3]]
+==== LZ 4-3: Offenheit und Erweiterbarkeit als wichtige Aspekte für die Weiterentwicklung von APIs interpretieren
+
+Teilnehmer:innen kennen Postel's Law, die Bedeutung von Forward und Backward Compatibility und welchen immensen Einfluss diese auf die Möglichkeit der Weiterentwicklung von API-Schnittstellen haben.
+Darüber hinaus erfahren Teilnehmer:innen, welche Konsequenzen dies für die Implementierung von APIs und deren Clients in streng und statisch typisierten Programmiersprachen hat.
+
+[[LZ-4-4]]
+==== LZ 4-4: Versionierung von APIs verstehen
+
+Teilnehmer:innen erlangen ein Verständnis für verschiedene Aspekte der Versionierung und wie sie innerhalb des Lebenszyklus eines API Produkts verwendet werden.
+
+[[LZ-4-5]]
+==== LZ 4-5: Good Practices für gelungenes API Design kennen
+
+Teilnehmer:innen lernen bewährte und verbreitete Ansätze für das Design von HTTP APIs kennen und verstehen die Vorteile und Herausforderungen.
+
+Hierzu zählen u. a.:
+
+* URL-Pfade
+* korrekte Verwendung von HTTP-Methoden oder Operationen für häufig benötigte Funktionalität wie Suchen, Filtern oder Sortieren
+* Formatvorschläge wie JSON:API
+* Problem Details for HTTP APIs (RFC 9457)
+* API Design Style Guides <<geewax>>
+
 
 // end::DE[]
 
@@ -27,8 +49,3 @@ tbd.
 ==== LG 4-2: TBD
 tbd.
 // end::EN[]
-
-[NOTE]
-====
-Die einzelnen Lernziele müssen nicht als einfache Aufzählungen mit Unterpunkten aufgeführt werden, sondern können auch gerne in ganzen Sätzen formuliert werden, welche die einzelnen Punkte (sofern möglich) integrieren.
-====
diff --git a/docs/04-api-design/references.adoc b/docs/04-api-design/references.adoc
@@ -1,18 +1,6 @@
 === {references}
 
-<<kruchten>>
-
-
-
-[NOTE]
-====
-Eine Quelle wird über `\<<label>>` referenziert. Dieses muss in `99-references/00-references.adoc` definiert sein.
-
-= = =
-
-A reference source is referenced via `\<<label>>`. The label has to be defined in `99-references/00-references.adoc`.
-====
-
+<<geewax>>
 
 // tag::DE[]
 // silence asciidoctor warnings

diff --git a/docs/99-references/00-references.adoc b/docs/99-references/00-references.adoc
@@ -9,24 +9,8 @@ Dieser Abschnitt enthält Quellenangaben, die ganz oder teilweise im Curriculum
 This section contains references that are cited in the curriculum.
 // end::EN[]
 
-[NOTE]
-====
-Aufbau eines Eintrags-Ankers:
-```
-- [[[label,Text der erscheint]]]
-```
-ACHTUNG: Die Labels dürfen nur Buchstaben beinhalten, keine Zahlen oder Sonderzeichen
-
-= = =
-
-Structure of an anchor:
-```
-- [[[label,text that will be shown]]]
-```
-ATTENTION: labels have to be non-numeric.
-====
-
 **A**
 
-- [[[api-business-model,API Business Models]]] ProgrammableWeb's 2020 Guide to API Business Models, ProgrammableWeb, May 2020.
+- [[[api-business-model,API Business Models]]] ProgrammableWeb's 2020 Guide to API Business Models, ProgrammableWeb, May 2020. https://www.mulesoft.com/sites/default/files/cmm_files/2020_Guide_to_API_Business_Models.pdf
 
+- [[[geewax,Geewax 2021]]] J Geewax: API Design Patterns. 1. Auflage, Manning Publications 2021