Tweet
Tweet

Slide 1

Slide 1 text

Vance Lucas • Co-Founder, Brightbit http://brightb.it Hypermedia APIs & Self-Building Apps

Slide 2

Slide 2 text

Who are You? • Vance Lucas • http://vancelucas.com • @vlucas (for heckling) • Brightbit • http://brightb.it • Design, Development & Consulting for web apps, mobile apps and APIs

Slide 3

Slide 3 text

What is a REST API? Hypermedia API?

Slide 4

Slide 4 text

Developed by Leonard Richardson http://martinfowler.com/articles/richardsonMaturityModel.html

Slide 5

Slide 5 text

“Level 3” is a pre- condition of REST Roy T. Fielding http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Slide 6

Slide 6 text

You must have hypermedia controls in your API to call it REST

Slide 7

Slide 7 text

“A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations.” Roy T. Fielding http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Slide 8

Slide 8 text

What are these “hypermedia controls”?

Slide 9

Slide 9 text

Two Key Things

Slide 10

Slide 10 text

Links

Slide 11

Slide 11 text

Forms

Slide 12

Slide 12 text

But you can’t make forms in an API! Whhaaaaa!

Slide 13

Slide 13 text

You Can. Kind of...

Slide 14

Slide 14 text

JSON Schema http://tools.ietf.org/html/draft-zyp-json-schema-03

Slide 15

Slide 15 text

JSON Schema { "description":"A person", "type":"object", "properties":{ "name":{"type":"string"}, "age" :{ "type":"integer", "maximum":125 } } }

Slide 16

Slide 16 text

URI Templates RFC 6570 http://tools.ietf.org/html/rfc6570

Slide 17

Slide 17 text

URI Templates http://uri.com/~{username}/ #-> http://uri.com/~fred/ http://uri.com/dictionary/{term:1}/{term} #-> http://uri.com/dictionary/c/cat http://uri.com/search{?q,lang} #-> http://uri.com/search?q=cat&lang=en

Slide 18

Slide 18 text

HAL Spec (Unofficial) http://stateless.co/hal_specification.html

Slide 19

Slide 19 text

HAL Specification { "_links": { "self": { "href": "/orders" }, "next": { "href": "/orders?page=2" }, "search": { "href": "/orders?id={order_id}" } }, "_embedded": { "order": [ { "_links": { "self": { "href": "/orders/123" }, "customer": { "href": "/u/bob", "title": "Bob" } }, "total": 30.00, "currency": "USD", "status": "shipped", "placed": "2011-01-16", } ] } }

Slide 20

Slide 20 text

Link “rel” Types http://www.iana.org/assignments/link-relations/link- relations.xml

Slide 21

Slide 21 text

No official spec for linking or describing resources for JSON or XML APIs

Slide 22

Slide 22 text

Too Boring; Didn’t Listen: Link and describe resources however you want, but be consistent.

Slide 23

Slide 23 text

DEMO TIME! App: https://github.com/vlucas/brightbudget-app API: https://github.com/vlucas/brightbudget-web

Slide 24

Slide 24 text

Questions? Rate this talk: https://joind.in/6205