From 9caa8bbe568c10b5362c72211207dad3f891b14d Mon Sep 17 00:00:00 2001 From: Falk Sippach Date: Wed, 20 Nov 2024 23:57:46 +0100 Subject: [PATCH] #8 initial version of chapter 4 --- docs/04-api-design/00-structure.adoc | 4 +- docs/04-api-design/01-duration-terms.adoc | 16 ++------ docs/04-api-design/02-learning-goals.adoc | 45 ++++++++++++++++------- docs/04-api-design/references.adoc | 14 +------ docs/99-references/00-references.adoc | 20 +--------- 5 files changed, 39 insertions(+), 60 deletions(-) diff --git a/docs/04-api-design/00-structure.adoc b/docs/04-api-design/00-structure.adoc index 99272cd..c09b5cb 100644 --- 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 index b5b42ce..9d0f2a5 100644 --- 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 index 034af45..4030fef 100644 --- 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 <> + // 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 index eac724b..3160f1e 100644 --- a/docs/04-api-design/references.adoc +++ b/docs/04-api-design/references.adoc @@ -1,18 +1,6 @@ === {references} -<> - - - -[NOTE] -==== -Eine Quelle wird über `\<