A brief look into building Web APIs with RDF, JSON-LD, and Hydra.

1. Creating Web APIs
with JSON-LD and RDF

2. About Me
Donald Smith
Sr. Software Engineer at Argo

3. Creating Web APIs
with JSON-LD and RDF

4. Why RESTful isn’t
enough…

5. Media Types
Atom
JSON
Collection+JSON
HAL
SIREN
Or…
Whatever I want!

6. These media types
are OK, but…

7. They don’t describe
my data

8. What is data?

10. Nothing without
applied meaning

11. Out of band
knowledge required

12. We want Information
not data

13. But JSON has won on
the web!

14. But, it’s not good
enough

15. A programmer adds
meaning to data

16. What if a machine could
understand information
instead?

17. RDF

18. What is RDF?

19. Resource Description
Framework

20. RDF is a standard model
for data interchange on
the Web

21. What does it do?
• Data merging even if underlying schemas differ
• Supports the evolution of schemas over time
without requiring consumers to change
• Eliminates data silos between your applications
• Allows you to ask questions of your data in a
standard way

22. The Basics

23. The Triple

24. Think of a sentence
written by a first grader

25. Donald owns a dog.
His name is Barley.

26. Yes, I like beer

27. a lot

28. Triple Composition
• Made up of three parts (hence Triple)
• The Subject
• The Predicate
• The Object

29. Sentence To Triple
Donald owns a dog.
subject predicate object

30. <Donald> <owns> <Barley>
subject predicate object

31. Um, this doesn’t look
better than JSON

32. Universal Uniqueness
• Triples use IRIs to uniquely identify Things in the Universe.
• IRIs allow us to use terms that are specific and universal
• IRIs are URIs, but internationalized

33. Expressed as a graph
Donald Barley
subject predicate object
owns

34. As JSON
{
"id": "people/Donald",
"type": "Person",
"name": "Donald",
"owns": {
"id": "animal/Barley",
"type": "Dog",
"name": "Barley"
}
}

35. As RDF
<http://example.com/people/Donald> <http://www.w3.org/
1999/02/22-rdf-syntax-ns#type> <http://schema.org/
Person> .
<http://example.com/people/Donald> <http://schema.org/
givenName> "Donald"^^xsd:string .
<http://example.com/people/Donald> <http://schema.org/
owns> <http://example.com/animals/Rover> .
<http://example.com/animals/Barley> <http://www.w3.org/
1999/02/22-rdf-syntax-ns#type> <http://dbpedia.org/
ontology/Dog> .
<http://example.com/animals/Barley> <http://schema.org/
givenName> "Barley"^^xsd:string .

36. Whoa, I thought you said
it was better than JSON?
That’s unreadable!

37. It even repeats itself!

38. GTFO!

39. Ok, ok. You’re right.

40. RDF was created for
machines. Not humans.

41. There is a solution.
Turtle!

42. Example in Turtle
@base <http://example.com/> .
@prefix schema: <http://schema.org/> .
@prefix db: <http://dbpedia.org/ontology/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
<people/Donald> a schema:Person ;
schema:givenName "Donald"^^xsd:string ;
schema:owns <animals/Barley> .
<animals/Barley> a db:Dog ;
schema:givenName "Barley"^^xsd:string .

43. Cool stuff?
• RDF is just a way of making statements about
Things.
• There is no order in RDF unlike JSON objects.
• To assert information about a given subject, you
don’t have to know where in the hierarchy that it
exists. We just use the subjects IRI.

44. RDF allows us to say
anything about any Thing
in the Universe.

45. Whatever man, this stuff
looks confusing and
stupid. I’ll stick to JSON.

46. That’s ok. That’s cool.
Some smart guys thought
you’d say that.

47. JSON-LD
• The goal was to require as little effort as possible
from developers
• There are a ton of web APIs out there. Changing to
a new format would break a lot of stuff
• JSON-LD lets us add semantic meaning without
breaking.

48. JSON-LD Context
{
"@context": {
"id": "@id",
"type": "@type",
"@base": "http://example.com/",
"Dog": "http://dbpedia.org/ontology/Dog",
"Person": "http://schema.org/Person",
"name": "http://schema.org/givenName",
"owns": "http://schema.org/owns"
},
"id": "people/Donald",
"type": "Person",
"name": "Donald",
"owns": {
"id": "animal/Barley",
"type": "Dog",
"name": "Barley"
}
}

49. The JSON object is
preserved. Existing
applications won’t break.

50. Let’s take a look…

51. Questions?

52. Media Types
• JSON-LD: application/ld+json
• Turtle: text/turtle
• N-Triples: application/n-triples
• N-Quads: application/n-quads
• RDF/XML: application/rdf+xml (Don’t use this one)

53. No need for another media
type
• The media type isn’t that relevant anymore
• Any schema or data model can be described with
RDF.
• Think of it as a language that everyone speaks.

54. JSON Web APIs
• Existing Web APIs can leverage JSON-LD to
promote data exchange between Applications
• Existing Web APIs that don’t or won’t support
JSON-LD is ok too. You can inject an @context into
a JSON fragment using out-of-band knowledge
and still use it as RDF
• JSON-LD supports both expansion and
compaction

55. JSON-LD Expansion &
Compaction

56. Merging data sources
My website Mike’s website
{
"@context": {
"id": "@id",
"type": "@type",
"@base": "http://donald.com/",
"Dog": "http://dbpedia.org/ontology/Dog",
"Person": "http://schema.org/Person",
"name": "http://schema.org/givenName",
"owns": "http://schema.org/owns"
},
"id": "people/Donald",
"type": "Person",
"name": "Donald",
"owns": {
"id": "animal/Barley",
"type": "Dog",
"name": "Barley"
}
}
{
"@context": {
"identifier": "@id",
"objectType": "@type",
"@base": "http://mike.com/",
"canine": "http://dbpedia.org/ontology/Dog",
"human": "http://schema.org/Person",
"called": "http://schema.org/givenName",
"ownerOf": "http://schema.org/owns"
},
"identifier": "me",
"objectType": "human",
"called": "Mike",
"ownerOf": {
"identifier": "canine/Bob",
"objectType": "canine",
"called": "Bob"
}
}

57. Expansion
• Each one is sent through the expansion algorithm
to output RDF
<http://mike.com/canine/Bob> <http://schema.org/givenName> "Bob" .
<http://mike.com/canine/Bob> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://dbpedia.org/ontology/Dog> .
<http://mike.com/me> <http://schema.org/givenName> "Mike" .
<http://mike.com/me> <http://schema.org/owns> <http://mike.com/canine/Bob> .
<http://mike.com/me> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Person> .
<http://donald.com/animal/Barley> <http://schema.org/givenName> "Barley" .
<http://donald.com/animal/Barley> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://dbpedia.org/ontology/Dog> .
<http://donald.com/people/Donald> <http://schema.org/givenName> "Donald" .
<http://donald.com/people/Donald> <http://schema.org/owns> <http://donald.com/animal/Barley> .
<http://donald.com/people/Donald> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Person> .
My website
Mike’s website

58. Merge the triples into a
Single Graph
<http://donald.com/animal/Barley> <http://schema.org/givenName> "Barley" .
<http://donald.com/animal/Barley> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://dbpedia.org/ontology/Dog> .
<http://donald.com/people/Donald> <http://schema.org/givenName> "Donald" .
<http://donald.com/people/Donald> <http://schema.org/owns> <http://donald.com/animal/Barley> .
<http://donald.com/people/Donald> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Person> .
<http://mike.com/canine/Bob> <http://schema.org/givenName> "Bob" .
<http://mike.com/canine/Bob> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://dbpedia.org/ontology/Dog> .
<http://mike.com/me> <http://schema.org/givenName> "Mike" .
<http://mike.com/me> <http://schema.org/owns> <http://mike.com/canine/Bob> .
<http://mike.com/me> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://schema.org/Person> .

59. Compaction with different
Context
"@context": {
"id": "@id",
"type": "@type",
"doggy": "http://dbpedia.org/ontology/Dog",
"peeple": "http://schema.org/Person",
"namey": "http://schema.org/givenName",
"hazIt": "http://schema.org/owns"
}

60. {
"@context": {
"id": "@id",
"type": "@type",
"doggy": "http://dbpedia.org/ontology/Dog",
"peeple": "http://schema.org/Person",
"namey": "http://schema.org/givenName",
"hazIt": "http://schema.org/owns"
},
"@graph": [
{
"id": "http://donald.com/people/Donald",
"type": "peeple",
"namey": "Donald",
"hazIt": {
"id": "http://donald.com/animal/Barley"
}
},
{
"id": "http://mike.com/canine/Bob",
"type": "doggy",
"namey": "Bob"
},
{
"id": "http://mike.com/me",
"type": "peeple",
"namey": "Mike",
"hazIt": {
"id": "http://mike.com/canine/Bob"
}
},
{
"id": "http://donald.com/animal/Barley",
"type": "doggy",
"namey": "Barley"
}
]
}

61. Questions?

62. Web APIs
• So far we only have looked at resolving unlike
terms into uniform machine readable URIs
• How do we build an API with this stuff?

63. Hydra
No, not this one

64. Hydra

65. Hydra
• Currently a W3C draft specification
• Hydra is a lightweight vocabulary to create
hypermedia-driven Web APIs. By specifying a
number of concepts commonly used in Web APIs it
enables the creation of generic API clients.

66. Let’s take a look…

67. Thanks!