Creating Web APIs with JSON-LD and RDF

Creating Web APIs with JSON-LD and RDF

About Me

Donald Smith Sr. Software Engineer at Argo

Creating Web APIs with JSON-LD and RDF

Why RESTful isn’t enough…

Media Types

AtomJSONCollection+JSONHALSIREN

Or… Whatever I want!

These media types are OK, but…

They don’t describe my data

What is data?

Nothing without applied meaning

Out of band knowledge required

We want Information not data

But JSON has won on the web!

But, it’s not good enough

A programmer adds meaning to data

What if a machine could understand information

instead?

RDF

What is RDF?

Resource Description Framework

RDF is a standard model for data interchange on

the Web

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

The Basics

The Triple

Think of a sentence written by a first grader

Donald owns a dog.His name is Barley.

Yes, I like beer

a lot

Triple Composition

• Made up of three parts (hence Triple)

• The Subject

• The Predicate

• The Object

Sentence To Triple

Donald owns a dog.

subject predicate object

<Donald> <owns> <Barley>


Um, this doesn’t look better than JSON

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

Expressed as a graph

Donald Barley


owns

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

}}

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 .

Whoa, I thought you said it was better than JSON?

That’s unreadable!

It even repeats itself!

GTFO!

Ok, ok. You’re right.

RDF was created for machines. Not humans.

There is a solution.

Turtle!

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 .

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.

RDF allows us to say anything about any Thing

in the Universe.

Whatever man, this stuff looks confusing and

stupid. I’ll stick to JSON.

That’s ok. That’s cool. Some smart guys thought

you’d say that.

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.

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" }}

The JSON object is preserved. Existing

applications won’t break.

Let’s take a look…

Questions?

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)

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.

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

JSON-LD Expansion & Compaction

Merging data sourcesMy 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" }}

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

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> .

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" }

{ "@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" } ]}

Questions?

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?

HydraNo, not this one

Hydra

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.

Let’s take a look…

Thanks!