Hysterisch gewachsen - Wege zu einer stabilen API

Enterprise Software hat erfahrungsgemäß eine lange Lebenszeit, weswegen die Wartbarkeit ein wichtiger Aspekt während der Entwicklung ist. Wie aber vermeidet man das Chaos in Projekten, welches lang läufig als historisch gewachsen bezeichnet wird? Mit leicht nachvollziehbaren Beispielen, zeige ich wie man mit einer Schichtenarchitektur eine stabile API entwickeln kann. Dabei werden Fragen geklärt wie:
• Qualität und Wartbarkeit
• Architektur und Design Pattern für APIs
• API Dokumentation und Versionierung

--------------------------------------------------------------------------------------------------
Homepage : https://elmar-dott.com
AnchorFM : https://anchor.fm/elmar-dott
Twitter - https://twitter.com/ElmarDott
GitHub - https://github.com/ElmarDott
Lbry - https://lbry.tv/@elmar.dott:8
BitChute - https://www.bitchute.com/channel/3IyCzKdX8IpO/
--------------------------------------------------------------------------------------------------

Transcript

1. Hysterisch gewachsen -
   Wege zu einer stabilen API
   (c) 2020 M. Schulz
   

   View Slide

2. The Author
   + Project Manager + Consultant + Writer + Speaker + Trainer +
   CC BY-ND
   Marco Schulz ElmarDott
   studied at HS Merseburg, Germany, computer science and
   holds an engineers degree in software engineering. The
   main topics in his field of work are Software
   Architectures, automatism of the software development
   process and Software Configuration Management. Since
   more than 15 years he work in different large Web
   Application Projects. Currently he work as independent
   Consultant, Trainer and publish plently articles in several
   computer magazines. Mail: marco.schulz@outlook.com
   JCON 2020 M. Schulz
   

   View Slide

3. Agenda
   ● Beispiele zu einer API
   ● Design Pattern
   ● Änderungen und Wartbarkeit
   ● Dokumentation mit API Guardian
   ● RESTful API & Swagger
   ● API Checkliste
   CC BY-ND
   JCON 2020 M. Schulz
   

   View Slide

4. Bekannte APIs
   CC BY-ND
   JSON
   JavaScript Object
   Notation
   PDF
   Portable Document
   Format
   XML
   Extensible Markup
   Language
   // rudimentäre APIs
   
   flexjson
   
   jackson
   // mehrere APIs
   SAX – Simple API for XML
   DOM – Document Object
   Model
   Stax – Streaming API for XML
   // Herstellerformat
   iText vs. OpenPDF
   JCON 2020 M. Schulz
   

   View Slide

5. Pattern: Adaptor / Fassade / Proxy
   CC BY-ND
   Adaptor: Auch bekannt als Wrapper, koppelt eine Schnittstelle zu
   einer anderen, die nicht kompatibel sind.
   Facade: bündelt mehrere Schnittstellen zu einer vereinfachten
   Schnittstelle.
   Proxy: ist eine Verallgemeinerung einer komplexen Schnittstelle. Es
   kann als Komplement zur Fassade verstanden werden, die mehrere
   Schnittstellen zu einer Einzigen zusammenfasst.
   JCON 2020 M. Schulz
   

   View Slide

6. Änderungen und Wartbarkeit
   CC BY-ND
   // Java Standard API
   List collection = new ArrayList<>();
   // Userdefined Project based API
   IList collection = new ListImpl<>();
   Architektur & Strucktur
   • my.pkg.business: Interfaces
   • my.pkg.application: Implementierungen
   • my.pkg.application.hepler: Hilfsklassen
   JCON 2020 M. Schulz
   

   View Slide

7. Dokumentation mit API Guardian
   CC BY-ND
   
   org.apiguardian
   apiguardian-api
   1.1.0
   
   ●
   DEPRECATED: Veraltet, sollte nicht weiterverwendet werden.
   ●
   EXPERIMENTAL: Kennzeichnet neue Funktionen, auf die der Hersteller gerne
   Feedback erhalten würde. Mit Vorsicht verwenden, da hier stets Änderungen
   erfolgen können.
   ●
   INTERNAL: Nur zur internen Verwendung, kann ohne Vorwarnung entfallen.
   ●
   STABLE: Rückwärts kompatibles Feature, das für die bestehende Major-Version
   unverändert bleibt.
   ●
   MAINTAINED: Sichert die Rückwärtsstabilität auch für das künftige Major-
   Release zu.
   JCON 2020 M. Schulz
   

   View Slide

8. RESTful
   CC BY-ND
   01: RolesDO role = rolesDAO.find(roleName);
   02: String json = rolesDAO.serializeAsJson(role);
   03: if (role != null) {
   04: response = Response.status(Response.Status.OK)
   05: .type(MediaType.APPLICATION_JSON)
   06: .entity(json)
   07: .encoding("UTF-8")
   08: .build();
   09: } else {
   10: response = Response
   11: .status(Response.Status.NOT_FOUND)
   12: .build();
   13: }
   JCON 2020 M. Schulz
   

   View Slide

9. Swagger
   CC BY-ND
   JCON 2020 M. Schulz
   

   View Slide

10. API Checkliste
    CC BY-ND
    ●
    Möglichst gegen Interfaces programmieren
    ●
    KISS: Keep it simple, stupid
    ●
    Wiederkehrende Strukturen verwenden
    ●
    Interfaces möglichst generell benennen
    ●
    Implementierungen nach deren Spezialisierung benennen
    ●
    Ausfühliche Dokumentation der Interfaces
    ●
    API Änderungen in einem Release bündeln
    ●
    Auf Kompatibilität achten
    JCON 2020 M. Schulz
    

    View Slide

11. Thank you / Danke / Gracias
    CC BY-ND
    JCON 2020 M. Schulz
    

    View Slide