Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

initial version of chapter 4 #9

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

initial version of chapter 4 #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9caa8bb
#8 initial version of chapter 4
sippsack Nov 20, 2024
f7b84a5
Merge branch 'main' into chapter-4-initial-version
dret Nov 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/04-api-design/00-structure.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Das war einfach ;-)

// end::EN[]

include::01-duration-terms.adoc[{include_configuration}]
Expand Down
16 changes: 3 additions & 13 deletions docs/04-api-design/01-duration-terms.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API-Design eher ohne Bindestrich? So wie im Titel?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wir müssen uns generell überlegen, wie wir es mit der Rechtschreibung handhaben wollen. Ich glaube, dass "API-Design" tatsächlich die korrekte deutsche Schreibweise wäre?!? Mir gefällt das aber auch nicht und ich schreibe es deshalb selbst auch immer ohne Bindestrich. In jedem Fall sollten wir es überall einheitlich schreiben.

In diesem Zusammenhang müssen wir uns ebenfalls einigen, welchen Artikel wir für "API" verwenden. Ich persönlich präferiere "die API", während manche Kolleg:innen aus den Print Medien mir das hartnäckig in "das API" korrigieren...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"API-Design" finde ich furchtbar, aber vielleicht sagt der Duden ja das muss so sein?

Und das deutsche API. Ich bin Neutrum-Fan. Ist ja nicht extrem weiblich, so ein API. Aber @sippsack, was meinst Du? Mir will scheinen die "die" Variante ist zumindest mal nicht unüblich in Deutschland?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ich versehe Deinen Punkt mit dem Neutrum. Unterstützer des Femininums argumentieren, dass API für ......schnittstelle steht. Und in der deutschen Sprache ist es eben "die Schnittstelle". Wie gesagt ist es mir gleich, nur einheitlich sollte es sein.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Falls es da keine Opposition gibt wäre ich persönlich happy mit "das".


// 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.
====
45 changes: 31 additions & 14 deletions docs/04-api-design/02-learning-goals.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API-Schnittstellen -> APIs? Sonst ist es ein bisschen doppelt und fuer mich auch leicht verwirrlich: Hat das API eine Schnittstelle?


* 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API-Design -> 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API-Schnittstellen -> APIs (wie oben)

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API Produkt -> API (sonst erscheint hier der Begriff etwas ueberraschend)


[[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[]

Expand All @@ -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.
====
14 changes: 1 addition & 13 deletions docs/04-api-design/references.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Vielleicht auch noch https://api-patterns.org/book/ ?


// tag::DE[]
// silence asciidoctor warnings
Expand Down
20 changes: 2 additions & 18 deletions docs/99-references/00-references.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-models,API Business Models]]] ProgrammableWeb's 2020 Guide to API Business Models, ProgrammableWeb, May 2020.
- [[[api-business-models,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