Wie soll ich den REST verstehen?

Das Ende aller privaten Schnittstellenspezifikationen

+DietrichSchulten / Kristian Köhler

Wer sind wir?

  • +DietrichSchulten
  • Kristian Köhler

010101010101..

How to get a cup of coffee?

Richardson Maturity Model

  • Level 0: Swamp of POX
  • Level 1: Resources
  • Level 2: HTTP verbs
  • Level 3: Hypermedia controls

Jacks Umsetzung

  • Mehr Schicht Architektur
    • AJAX basiertes Frontend
    • REST basiertes Service Backend
  • Service Backend soll JSON "sprechen"
  • Hypermedia driven (RMM Level 3!)

Hypermedia (-Driven)

  • Hypertext
    • Darstellung von Inhalt und Steuerung
    • Verlinken von Ressourcen
  • HATEOAS - Hypermedia as the Engine of Application State
    • Dissertation Roy Fielding
    • State Transition

JSON und Hypermedia?


{
    "name": "Kaffeehaus Hagen",
    "menu": [{
        "price": 2.8,
        "priceCurrency": "EUR",
        "product": {
            "name": "Latte Macchiato",
            "id": "9052002"
        }
    }]
}
    

JSON und Hypermedia!

  • HAL - Hypertext Application Language
  • JSON-LD - Linked Data
  • JSON Hyperschema
  • Siren
  • Collection+JSON
  • Uber
  • ...

HAL - Hypertext Application Language

  • Internet Draft - ietf.org
  • MediaType: application/hal+json

{
    "_links": {
        "self": { "href": "/orders" },
        "next": { "href": "/orders?page=2" },
        "curies": [{"name": "ea", 
                    "href": "http://example.com/docs/rels/{rel}", 
                    "templated": true }],
        "ea:find": {
            "href": "/orders{?id}",
            "templated": true
        }]
    },
    "currentlyProcessing": 14,
    "shippedToday": 20,
...

Kann ein anderes Team die "Schnittstelle" verstehen?

  • Was bedeuten die Links?
  • Welche Aktionen kann ich mit Ihnen durchführen?
  • Wie sehen meine Resourcen aus? Attribute?

IANA.org

IANA is responsible for maintaining many of the codes and numbers contained in a variety of Internet protocols

JSON Schema


    Content-Type: application/json;
          profile=http://example.com/my-schema#                                                                                        
    

{
	"title": "Example Schema",
	"type": "object",
	"properties": {
		"firstName": {
			"type": "string"
		},
		"age": {
			"description": "Age in years",
			"type": "integer",
			"minimum": 0
		}
	},
	"required": ["firstName", "lastName"]
}
    

JSON Schema in HAL


     Content-Type: application/hal+json;
          profile=http://example.com/my-schema
    

{
    "_links": {
        "self": { "href": "/orders" },
        "next": { 
            "href": "/orders?page=2",
            "profile" : "http://example.com/my-schema"
        }]
    },
    "currentlyProcessing": 14,
    "shippedToday": 20,
...

Jacks Resultierendes JSON Dokument


    Content-Type: application/json;
          profile=http://jax.de/coffeeshop-schema                                                                                    
    

    {
    "_links": { "curies":[{ "href": "/rels/{rel}", "name": "hagen"}]},
    "name": "Kaffeehaus Hagen",
    "_embedded": {
        "hagen:menu": [{
            "price": 2.8,
            "priceCurrency": "EUR",
            "_embedded": {
                "hagen:product": {
                    "name": "Latte Macchiato",
                    "id": "9052002",
                    "_links": { "hagen:orders": { "href": "/orders" }}
                }
            }
        }, ...]
    }
}
    

Webseite fertig - Kunde glücklich!?

Und wie!

Neuer Auftrag!

Kunde hat weitere Shops gekauft!

Müssen nur integriert werden!

Handelt sich um gleiche Technologie!

Technologie des anderen Shops

  • Rest basiertes Backend
  • Service nutzt JSON
  • Media-Type: application/hal+json

Also alles kein Problem!

HAL != HAL

Semantic Gap


{
    "_links":{"curies":[{ "href": "/rels/{rel}","name":"hochland"}]},
    "name": "Hochland Kaffee",
    "_embedded": {
        "hochland:speisekarte": [{
        "preis": 2.8,
        "waehrung": "EUR",
            "_embedded": {
                "hochland:artikel": {
                    "artName": "Latte Macchiato",
                    "artNr": "9052002",
                    "_links": { "hochland:best": { "href": "/best" }}
                }
            }
        }, ...]
    }
}
    

Internet geht anders

Wie baue ich einen ReST Service
den jeder Client versteht?

MIME types
tragen die Bedeutung

MIME Type++

ALPS/APR und Json-LD

JSON-LD - Linked Data

  • JSON-basiertes format für Linked Data
  • W3C Recommendation
  • Beschreibt Bedeutung (<>JSON Schema)
  • Not about the Semantic Web at all (Manu Sporny)

Schema.org Vokabular

  • Google, Yahoo, Bing und Yandex
  • Google Structured Data
  • Integriert GoodRelations
  • Offener Prozess

Hydra Vokabular

  • Vokabular für Interaktionen in JSON-LD
  • Beschreibt Methoden von Ressourcen
  • Ermöglicht Verweis auf "Related Collections"
  • Interpretierbar für Maschinenclients

Was bedeuten die Attribute?


// application/ld+json
{
    "@context": {
        "@vocab":"http://schema.org/",
        "id": "productID"
    },
    "name": "Latte Macchiato",
    "id": "9052002"
}
oder "compacted"

// application/ld+json;profile="http://www.w3.org/ns/json-ld#compacted"
{
    "http://schema.org/name": "Latte Macchiato",
    "http://schema.org/productID": "9052002"
}
    

Aus Attributen werden Rels

{
    "@context": {
        "@vocab": "http://schema.org/",
        "menu": "makesOffer",          // hagen:menu
        "product": "itemOffered",      // hagen:product
        "orders": "orderedItem",       // hagen:orders
        "id": "productID",
        "hydra:property": {"@type":"@vocab"}
    },
    ...
}
    

Rels für Objekte und Collections

{ ...
    "name": "Kaffeehaus Hagen",
    "menu": [{                               //makesOffer
      "product": {                           //itemOffered
        "name": "Latte Macchiato",           //name
        "id" : "9052002",                    //productID
        "hydra:collection": [{
           "@id": "http://example.com/orders",
           "hydra:manages": {
               "hydra:property": "orders",   //orderedItem
               "hydra:subject": { "@type": "Order" }
           }
        }]
      }
    }]
}
    

Attribute und Rels "compacted"


{
  "http://schema.org/productID": "9052002",
  "http://schema.org/name": "Kaffeehaus Hagen",
  "http://schema.org/makesOffer": {                // menu
    "http://schema.org/itemOffered": {             // product
      "http://schema.org/name": "Latte Macchiato",
      "hydra:collection": {
        "@id": "http://example.com/orders",
        "hydra:manages": {
         "hydra:property": {
            "@id": "http://schema.org/orderedItem" //orders
         }, 
         "hydra:subject": {"@type": "http://schema.org/Order"}
        }
      }
...
    

How to get a cup of coffee?

Get a cup of coffee!

"hydra:collection": [
     {...
       "hydra:operation": {
         "hydra:method": "POST",
         "hydra:expects": {
           "hydra:supportedProperty": [
             {
               "@type": "PropertyValueSpecification",
               "hydra:property": "productID",
               "hydra:required": true,
               "defaultValue": "9052002",
               "readOnlyValue": true
             }
           ]
         }
       }}]...
    

POST /example.com/orders HTTP/1.1
...
{
"@context": "http://schema.org/",
"productID": "9052002"
}
    

Das Ende aller privaten Schnittstellenspezifikationen?

Beschreibung mittels HAL

  • HAL + JSON-Schema für Attribute
  • ALPS oder JSON-Hperschema für Transitions
  • HTTP Options als erste Variante
  • Vorrangig für private Schnittstellenspezifikationen
  • HAL + JSON-Schema optional

Beschreibung mittels JSON-LD / Hydra

  • JSON-LD: auf globale Verständlichkeit ausgelegt
  • Schema.org liefert das Vokabular für Internet-Themen
  • Hydra Client kann Interaktion voraussetzen
  • Schema.org deckt nicht alles ab
  • Hydra ist nicht final
  • Client libraries für Hydra fehlen

Welcher Content-Type?

  • Ein allumfassender Standard ist nicht in Sicht
  • Content Negotiation!

What's next?

  • JSON-LD Playground
  • Hydra Community Group besuchen: hydra-cg.com
    • Restbucks with Hydra
  • Eigenen Server um Hydra erweitern
    • https://github.com/dschulten/hydra-java
  • Client schreiben

Danke!

+DietrichSchulten

Kristian Köhler