Documented and Tested Microservices For Fun And Profit

Documented and Tested Microservices For Fun And Profit

Oliver Trosien, ePages GmbH

WTF is a "REST endpoint"? - Roy Fielding

• Über mich: Langjähriger Softwareentwickler bei ePages.
• Fangen wir mit einem einen kleinen Werbeblock an. Was macht ePages? 100.000 Shops, Hostingprovider und Telekommunikations. Kooperieren mit über 60 Technologiepartnern Standorte in Hamburg, Jena, Barcelona, London, New York Übrigens: wir suchen noch Softwareentwickler für unseren Standort HH

Documenting REST APIs

apihandyman.io

• Thema, das unter uns Entwicklern eher unbeliebt ist - Dokumentation.
• Zwei Teilbereiche: Menschenlesbare Dokumentation (Handbücher, User Guide...), Maschinenlesbare Dokumentation (IDL)
• Drei Ziele: vollständig, fehlerfrei, aktuell
• Lüsungen im Java-Kontext.

How RESTful are you?

• Richardson Maturity Model
• Level 2: Auf die Idee mit einem GET den Suchindex löschen zu lassen kommt heutzutage nur noch Apache Solr.
• Je nach Kategorisierung der eigenen API ist eine andere Art der Dokumentation nötig.
• Martin Fowler: "The Glory of REST" / Level 3 / Heiligenschein (ernst gemeint?)
• Auch Level 0-2 APIs haben ihre Daseinsberechtigung, sie sind nur nicht ganz "im Sinne des Erfinders"

How RESTful do youwant to be?

• Die Frage sollte daher eher lauten - wo im RMM möchtest du dich platzieren?

Interface Description Languages

• WSDL (2001)
• | WADL (2009)
• | Swagger (2009)
• | RESTdesc (2010)
• | I/O Docs (2011)
• | JSON Home (2012)
• | RAML (2013)
• | API Blueprint (2013)
• | JSON Hyper-Schema (2013)
• | Hydra (2014, draft)
• | ALPS (2014, draft)
• | UBER (2015, draft)
• | CPHL (2015, brain-storming)
• ..

• WSDL 1.1 als Referenz, 2000 Roy Fieldings Dissertation "Design of Network-based Software Architectures"
• Swagger ist von den genannten Tools sicherlich das populärste - eines der Key features ist die Interaktive Konsole
• Wir verwenden für einen Teil der API Dokumentation RAML, eine auf YAML basierende Spezifikationssprache.
• Nachteile von swagger: zu URI-zentriert, keine Unterstützung von Querschnitts-Aspekten (Auth, Errors), "undichte" Abstraktion - zieht ggf. fehlerhafte Rückschlüsse , groß, schwemmt den Code mit eigenen Annotations auf.

Media Types

• Plain-old XML
• | Proprietary JSON
• | HAL (2011)
• | JSON-LD (2011)
• | Collection+JSON (2011)
• | JSON API (2013)
• | Hydra (2014)
• | Mason (2014, draft)
• | SIREN (2015, draft)
• ..

• HAL: IETF Draft, Mike Kelly, http://tools.ietf.org/html/draft-kelly-json-hal
• JSON-LD: W3C Recommendation, M. Lanthaler, http://www.w3.org/TR/json-ld/
• Hydra: Baut auf LSON-LD auf. W3C Unofficial draft M. Lanthaler, http://www.markus-lanthaler.com/hydra/spec/latest/core/
• Collection+JSON (vgl. mit Atom Feed) Mike Amunndsen, http://amundsen.com/media-types/collection/format/
• Mason: Jørn Wildt (vgl. mit Siren, Hydra)

HAL

					{
  "_links": {
    "self": {
      "href": "http://otrosien:8081/pizzas"
    }
  },
  "_embedded": {
    "pizzas": [
      {
        "name": "Pizza Salami",
        "description": "The classic"
      }
    ]
  }
}
					

Spring-Data-REST

Spring WebMVC Spring-Data Spring-HATEOAS

• Repositories as resources with CRUD operations
• Supports HAL + ALPS + JSON Schema
• Ties your REST API to your data model

olivergierke/spring-restbucks

Follow your nose API

• Single well-known entry point
• Resources discoverable via link relations

Documentation style

• Focus on problem domain
• Focus on relations
• Be consistent
• Focus on URIs
• Repeating the obvious

The ePizza system

ePages-de/rnd-microservices-handson

Demo

Learnings

• IDL standards are still evolving
• Tool-support (usually) still poor
• Be correct, complete and current

Thank you!

For more info, feel free to contact us @epagesdevs epages.com/devjobs otrosien@epages.com ePages-de/codetalks2015