Presented at the Symfony Live Portland 2013 in Portland (Oregon), USA The recording of the talk is available at http://bit.ly/sl-portland2013-video

1. Building Next-Gen Web APIs
with JSON-LD and Hydra
Markus Lanthaler

2. Why do we
need a website?
Of course we
have a website
Why do we
need an API?
1995 2000 2005 2010
Of course we
have an API
Adapted from T. Vitvar’s and J. Musser’s ECOWS 2010 Keynote,
“ProgrammableWeb.com:Statistics, Trends, and Best Practices”

4. Using Web APIs is still challenging

6. Level 0:The Swamp of POX
Level 1: Resources
Level 2: HTTPVerbs

8. {
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z"
}
http://example.com/issues/cso29ax

9. BILLION DOLLAR
QUESTION
the

10. {
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z"
}
http://example.com/issues/cso29ax
http://example.com/issue/{id}/comments/

12. {
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z",
"comments": "/issues/cso29ax/comments/"
}
http://example.com/issues/cso29ax

13. Level 0:The Swamp of POX
Level 1: Resources
Level 2: HTTPVerbs
Level 3: Hypermedia Controls

14. {
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z",
"comments": "/issues/cso29ax/comments/"
}
http://example.com/issues/cso29ax

15. Every API is a snowflake

16. Result: tightly coupled & brittle systems

17. {
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z",
"comments": "/issues/cso29ax/comments/"
}
http://example.com/issues/cso29ax

18. {
69 64: 63 73 6f 32 39 61 78
74 69 74 6c 65: 53 79 6d 66 6f 6e 79 20 4c 69 76 …
64 65 73 63 72 69 70 74 69 6f 6e: 50 72 65 70 61 …
69 73 5f 6f 70 65 6e: 01
63 72 65 61 74 65 64 5f 61 74: 32 30 31 32 2d 31 …
63 6f 6d 6d 65 6e 74 73: 2f 69 73 73 75 65 73 2f …
}
http://example.com/issues/cso29ax

19. Identifiers on the Web: URIs

20. Linked Data Principles
Tim Berners-Lee, 2006

21. JSON-LD

23. Make data self-descriptive by
mapping concepts to URLs

24. {
"id": "markus",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

25. {
"@context": {
"firstname": "http://schema.org/givenName",
"lastname": "http://schema.org/familyName",
"homepage": "http://schema.org/url"
},
"id": "markus",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

26. {
"@context": {
"firstname": "http://schema.org/givenName",
"lastname": "http://schema.org/familyName",
"homepage": "http://schema.org/url"
},
"@id": "/people/markus",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

27. {
"@context": {
"firstname": "http://schema.org/givenName",
"lastname": "http://schema.org/familyName",
"homepage": "http://schema.org/url"
},
"@id": "/people/markus",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

28. {
"@context": {
"firstname": "http://schema.org/givenName",
"lastname": "http://schema.org/familyName",
"homepage": "http://schema.org/url"
},
"@id": "/people/markus",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": { "@id": "http://www.markus-lanthaler.com/" }
}

29. {
"@context": {
"firstname": "http://schema.org/givenName",
"lastname": "http://schema.org/familyName",
"homepage": {
"@id": "http://schema.org/url", "@type": "@id" },
},
"@id": "/people/markus",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

30. {
"@context": {
"firstname": "http://schema.org/givenName",
"lastname": "http://schema.org/familyName",
"homepage": {
"@id": "http://schema.org/url", "@type": "@id" }
},
"@id": "/people/markus",
"@type": "http://schema.org/Person",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

32. {
"@context": {
"firstname": "http://schema.org/givenName",
"lastname": "http://schema.org/familyName",
"homepage": {
"@id": "http://schema.org/url", "@type": "@id" }
},
"@id": "/people/markus",
"@type": "http://schema.org/Person",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

33. {
"@context": "/contexts/person.jsonld",
"@id": "/people/markus",
"@type": "http://schema.org/Person",
"firstname": "Markus",
"lastname": "Lanthaler",
"homepage": "http://www.markus-lanthaler.com/"
}

34. CMF

37. {
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z",
"comments": "/issues/cso29ax/comments/"
}
http://example.com/issues/cso29ax

38. {
"@context": "/ctx/context.jsonld",
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z",
"comments": "/issues/cso29ax/comments/"
}
http://example.com/issues/cso29ax

39. {
"@context": "/ctx/context.jsonld",
"id": "cso29ax",
"title": "Symfony Live Portland 2013",
"description": "Prepare slides",
"is_open": true,
"created_at": "2012-11-26T04:49:44Z",
"comments": "/issues/cso29ax/comments/"
}
http://example.com/issues/cso29ax

40. {
"@id": "#comments",
"@type": "hydra:Link",
"supportedOperations": [
{
"@id": "#create-comment",
"@type": "hydra:CreateResourceOperation",
"label": "Creates a new comment",
"method": "POST",
"expects": "#Comment",
"returns": "#Comment"
}
]
}
http://example.com/api/doc

41. {
"@id": "#Comment",
"@type": "hydra:Class",
"supportedProperties": [
{
"property": "#text",
"required": true,
"readonly": false,
"writeonly": false
}
]
}
http://example.com/api/doc

44. /**
* An Issue tracked by the system.
*
* @HydraExpose()
*/
class Issue
{
/**
* The comments associated with this issue
*
* @HydraExpose()
* @HydraCollection("issue_comments")
* @HydraOperations("issue_comment_create")
*/
private $comments;
// ... other members and methods ...
}

45. $ php app/console hydra:generate:crud
--entity=MLDemoBundle:Issue
--route-prefix=/issues/
--with-write
--no-interaction
CRUD generation
Generating the CRUD code: OK
You can now start using the generated code!

46. /**
* Issue controller
*
* @Route("/issues")
*/
class IssueController extends HydraController
{
/**
* Creates a new Issue
*
* @Route("/", name="issue_create")
* @Method("POST")
*
* @HydraOperation(expect = "MLDemoBundleEntityIssue")
*
* @return MLDemoBundleEntityIssue
*/
public function collectionPostAction(Request $request)
{
...

49. Hydra Console

54. © 2013, Markus Lanthaler. Some Rights Reserved.
http://creativecommons.org/licenses/by-nc-sa/3.0/
Thank You

55. Questions?
Markus Lanthaler
http://www.markus-lanthaler.com
@MarkusLanthaler
mail@markus-lanthaler.com

56. Image Credits
(1) http://www.flickr.com/photos/justinwkern/3729649672/
(2) http://www.flickr.com/photos/alexdram/3095419858/
(3) http://www.flickr.com/photos/kaptainkobold/3203311346/
(11) http://info.cern.ch/hypertext/WWW/TheProject.html
(15) Adapted from http://www.flickr.com/photos/nebarnix/361650027/
(16) http://www.flickr.com/photos/joyoflife/1570126182/
(19) http://www.flickr.com/photos/rossiprojects/5592552858/
(21) http://www.flickr.com/photos/rossiprojects/5592552858/
(23) http://www.flickr.com/photos/clevercupcakes/4397152402/
(31) http://schema.org/Person
(36) http://www.vonwong.com/
(42) http://www.flickr.com/photos/jakecaptive/3205277810/
(47) http://www.flickr.com/photos/sis/126152933/