9 Schritte zur richtigen API

Facebooktwittergoogle_pluspinterestlinkedinmailFacebooktwittergoogle_pluspinterestlinkedinmail

Neue Software-Produkte benötigen meist ein Oberfläche zur Administration und zur Anzeige für normale Nutzer. Eine klare Trennung zwischen UI und Backend durch eine API ist dabei unabdingbar. Doch was muss beim Bau einer eigenen API beachtet werden. 9 wichtige Gedankenansätze finden sich hier.

#1 Definiere Anforderungen

❓Problem

Jeder Software-Entwickler kennt das Problem: Die gewünschte Software des Produkt-Managements ist (weit) weg von der fertigen implementierten Lösung. Dieses Problem kann auch zwischen Entwicklern und Nutzern der API (z.B. eine UI) sein.

💡Lösungen

  • Lass den Nutzer der API die Anforderungen selbst definieren.
  • Nutze TDD#1Test Driven Development: Definiere die REST Response bevor deren Implementierung entwickelt wird.
  • Benutze Labels#2Add, Remove and Search for Labels – Atlassian Documentation um Aufgaben und Probleme im Projektmanagement-Tool um zu markieren, ob eine Vordefinition benötigt wird.

#2 Informiere über API-Änderungen

❓Problem

Änderungen in der API werden immer in der Dokumentation abgebildet. Das ist sehr wichtig bei großen Änderungen, wie Umbenennung oder Löschung von Attributen.

💡Lösungen

  • Definiere und nutze API-Versionierung#3Version Number. Führe eine neue Version ein sobald große Änderungen eingeführt wurden.
    Hol dir Inspiration von Versionierungs-Konzepten anderer APIs: Microsoft#4Service Management Versioning, Amazon#5Common Query Parameters – Amazon Elastic Compute Cloud, Twitter#6REST APIs – Twitter Developers, Facebook#7Versioning – App DevelopmentThe goal for having versioning is for developers building apps to be able to understand in advance when an API or SDK might change. They help with web development, but are critical with mobile development because a person using your app on their phone may take a long time to upgrade (or may never upgrade). und viele andere#8How are REST APIs versioned? | Lexical Scope.
  • Informiere die API-Nutzer regelmäßig über Änderungen.
    Hol dir Inspiration über Release Notes von anderen Firmen: WordPress#9WordPress Versions, Mozilla#10Mozilla Firefox Web Browser – Mozilla Firefox Release Notes – Mozilla, GIMP#11GIMP – GIMP 2.6 Release Notes, Ubuntu#12Release – Ubuntu Wiki oder Android#13SDK Release Notes | Android Developers.

#3 Veröffentliche SDKs

❓Problem

Jede öffentliche API sollte von anderen Entwicklern auf der Welt genutzt werden. Es ist empfehlenswert Frameworks in meistgenutzten Programmiersprachen#14TIOBE Index | TIOBE – The Software Quality Company anzubieten um einfach auf die API zuzugreifen (SDK).

💡Lösungen

  • Entwickle und teile dein selbstentwickeltes SDK. Externe Entwickler können dies später verändern und erweitern.

#4 Nutze Automation Services

❓Problem

Bei jedem Ausrollen einer neuen Version müssen viele, sich wiederholende, Aufgaben erledigt werden.

💡Lösungen

  • Benutze Tools um diese Ausroll-, Test- oder Integrations-Schritte zu automatisieren. Diese Tools können entweder auf dem eigenen System ausgeführt#15Jenkins oder bequem auf anderem Servern angemietet#16Continuous Integration and Delivery – CircleCI werden.
  • Integriere diese Tools auch in deine tägliche Arbeit. Es gibt Plugin für z.B. GitHub#17GitHub Plugin – Jeenkins – Jenkins Wiki oder Confluence#18Git for Confluence | Atlassian Marketplace.

#5 Drink your own Champagne

❓Problem

Die selbstentwickelte API wird größer und schlechter wartbar werden. Nach mehreren Jahren ist es nicht mehr möglich, dass jeder Entwickler / QAler jede Funktionalität testen und verstehen kann. Jeder abgeschlossene Service / Einheit sollte nur eigenen Funktionalität testen.

💡Lösungen

  • Versuche deine API in (logisch) trennbare Einheiten zu schneiden#19The Art of Seperation of Concerns.
  • Habe keine Angst bestimmten Code für alle Einheiten zu nutzen#20Applying aspect oriented programming. Es wird immer Code geben, den du in mehreren Zusammenhängen nutzen kannst.
  • Habe keine Angst nach einiger Zeit diese Services und Einheiten wieder zu teilen oder zu vermischen. Konzepte und Ansätze sollten regelmäßig überdacht werden. Sei agil.

#6 Definiere verschiedene API Call Limits

❓Problem

Jede API hat anderen Einsatzgründe. Jeder Einsatzgrund wird verschieden oft genutzt.

💡Lösungen

    • Definiere verschiedene API Call Limits für verschiedene APIs.
    • Setze diese Grenzen anhand einer Konfiguration. Die ideale Grenze kannst du finden, wenn die API real benutzt wird.
    • Gib Informationen über das API Limit bei jeder Antwort an den Nutzer mit. Benutze den Header für diese Information, wie:
      X-RateLimit-Remaining: 5999
      X-Rate-Limit-Reset: 2015-02-20T13:14:34
      

#7 Nutze dem Cache

❓Problem

Jede API wird irgendwann Probleme durch zu viel Kommunikation doppelter Anfragen bekommen. Dies kann lange Antwortzeiten und sogar Ausfälle hervorrufen.

💡Lösungen

    • Nutze Caching-Implementierungen#21Varnish HTTP Cache – Varnish HTTP Cache. Diese können einfach eingestellt werden und optimieren die Performance.
    • Unterstütze die HTTP-Methode PURGE. Diese Methode ist nicht offiziell in einem RFC verabschiedet wurden, aber ist sinnvoll um den Cache zu leeren:
      GET product/shirt
      - product 'shirt' was not cached since last update
      - retrieves product 'shirt'
      - saves this object in cache
      
      GET product/shirt
      - gets the product 'shirt' from cache
      
      PURGE product/shirt
      - flushes and deleted the cached ressource 'shirt'
      
      GET product/shirt
      - product 'shirt' was not cached since last update
      - retrieves product 'shirt'
      - saves this object in cache
      
    • Implementiere Funktionen von HTTP wie Cache-Control#22Things Caches DoLast Modified#23Caching Tutorial for Web Authors and Webmasters und Expired.

#8 Organisiere Support

❓Problem

Externe Entwickler, die die API benutzen, werden Fehler finden oder neue Funktionen vorschlagen. Wie können sie diese Anfragen senden?

💡Lösungen

    • Überleg dir, wie du Feedback von Entwicklern bekommen kannst. Benutzt Foren, Blogs oder andere Dinge um mit Externen zu kommunizieren.

#9 Behind the Scenes

❓Problem

Um Probleme bei der API schnell zu bemerken sollten Informationen verteilt werden, was hinter den Kulissen passiert. Ist die API verfügbar? Gibt es aktuell Probleme?

💡Lösungen

    • Verteile Status-Informationen über dein System. Entwickle dies selbst#24Build a Health Check API for Services Underneath Your API – Runscope Blog, #25Health Checks (HTTP) – Consul by HashiCorp oder nutze die Vorteile eines Frameworks.
      Für Ideen und Vorschläge schau dir andere APIs an: GitHub#26GitHub System Status, Facebook#27Platform Status – Facebook for Developers, Twitter#28API Status – Twitter Developers oder Apple#29System Status – Apple Developers.
    • Benutze externe#30status.io – A Complete Status Platform Status Tools#31StatusDashboard | Downtime happens… be prepared. Damit sparst du dir die Selbstentwicklung.

Quellen   [ + ]

1. Test Driven Development
2. Add, Remove and Search for Labels – Atlassian Documentation
3. Version Number
4. Service Management Versioning
5. Common Query Parameters – Amazon Elastic Compute Cloud
6. REST APIs – Twitter Developers
7. Versioning – App DevelopmentThe goal for having versioning is for developers building apps to be able to understand in advance when an API or SDK might change. They help with web development, but are critical with mobile development because a person using your app on their phone may take a long time to upgrade (or may never upgrade).
8. How are REST APIs versioned? | Lexical Scope
9. WordPress Versions
10. Mozilla Firefox Web Browser – Mozilla Firefox Release Notes – Mozilla
11. GIMP – GIMP 2.6 Release Notes
12. Release – Ubuntu Wiki
13. SDK Release Notes | Android Developers
14. TIOBE Index | TIOBE – The Software Quality Company
15. Jenkins
16. Continuous Integration and Delivery – CircleCI
17. GitHub Plugin – Jeenkins – Jenkins Wiki
18. Git for Confluence | Atlassian Marketplace
19. The Art of Seperation of Concerns
20. Applying aspect oriented programming
21. Varnish HTTP Cache – Varnish HTTP Cache
22. Things Caches Do
23. Caching Tutorial for Web Authors and Webmasters
24. Build a Health Check API for Services Underneath Your API – Runscope Blog
25. Health Checks (HTTP) – Consul by HashiCorp
26. GitHub System Status
27. Platform Status – Facebook for Developers
28. API Status – Twitter Developers
29. System Status – Apple Developers
30. status.io – A Complete Status Platform
31. StatusDashboard | Downtime happens… be prepared

Kommentar hinterlassen

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.