One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014

Web APIs
Alexandre Bertails, Pellucid Analytics
@bertails
1 / 46

Web APIs
Who are the users of my API?
What do they do with it?
How will they interact with it?
2 / 46

Web APIs
Who are the users of my API?
What do they do with it?
How will they interact with it?
REST
hypermedia
HATEOAS
3 / 46

HTTP, back to the basics
resources
representations
semantics
4 / 46

HTTP interactions
$HEADhttps://data.example.com/company/
Content-Type:application/json
a media type specification sets out
formats
processing model
hypermedia controls
for its representation
5 / 46

media type
Content-Type and Media Type as defined in HTTPBIS
HTTP uses Internet Media Types [RFC2046] in the Content-Type
(Section 3.1.1.5) [...] header fields in order to provide open and
extensible data typing [...]. Media types define both a data format and
various processing models.
6 / 46

IANA registry for media types
IANA registry for Media Types
Name Template Reference
json application/json [RFC7158]
7 / 46

JSON
The JavaScript Object Notation (JSON) Data Interchange Format [RFC7159]
JSON can represent four primitive types (strings, numbers, booleans,
and null) and two structured types (objects and arrays).
8 / 46

JSON
The JavaScript Object Notation (JSON) Data Interchange Format [RFC7159]
JSON can represent four primitive types (strings, numbers, booleans,
and null) and two structured types (objects and arrays).
No processing model defined in JSON! (neither in JSON-LD, HAL,
etc.)
9 / 46

extending media type semantics
what wouldthe RESTafarian do?
probably use a vendor specific media type
Content-Type:application/vnd.example.company+json
10 / 46

Linkheader
rel=profile Link header
The 'profile' link relation type [...] allows resource representations to
indicate that they are following one or more profiles. A profile is
defined not to alter the semantics of the resource representation
itself, but to allow clients to learn about additional semantics [...] in
addition to those defined by the media type [...].
Link:<https://data.example.com/ontology#Company>;rel="profile"
11 / 46

HATEOAS?
Hypermedia can be the engine of a single API.
Hypermedia cannot be the engine of cross-API interactions.
Ruben Verborgh, Hypermedia Cannot be the Engine
12 / 46

focusing on data
HATEOAS is like a hypermedia state machine
data modeling is a special case for application state
media type encodes kind/type
but few missing interactions eg. CRUD
13 / 46

data patterns in JSON
encodings
links
types
disambiguating schemas
Let's make JSON a hypermedia format :-)
14 / 46

a 1st version
an Industry entity
$GEThttps://data.example.com/industry/q6po09
{
"id":"q6po09",
"name":"Fruits"
}
a Company entity
$GEThttps://data.example.com/company/c34dap
{
"id":"c34dap",
"name":"Apple",
"ticker":"AAPL",
"industry":"q6po09"
}
documentation probably available at something like
https://data.example.com/api/documentation 15 / 46

things, not String-s
an Industry entity
{
"@id":"https://data.example.com/industry/q6po09",
"name":"Fruits"
}
a Company entity
{
"@id":"https://data.example.com/company/c34dap",
"name":"Apple",
"ticker":"AAPL",
"industry":{"@id":"https://data.example.com/industry/q6po09"}
}
16 / 46

this is its own @id
an Industry entity
{
"name":"Fruits"
}
a Company entity
{
"name":"Apple",
"ticker":"AAPL",
}
17 / 46

what are we dealing with?
an Industry entity
{
"type":"Industry",
"name":"Fruits"
}
a Company entity
{
"type":"Company",
"name":"Apple",
"ticker":"AAPL",
}
18 / 46

@type+ URL
an Industry entity
{
"@type":{"@id":"https://data.example.com/ontology#Industry"},
"name":"Fruits"
}
a Company entity
{
"@type":{"@id":"https://data.example.com/ontology#Company"},
"name":"Apple",
"ticker":"AAPL",
}
19 / 46

disambiguating attributes [1/3]
How to distinguish an industry's name from a company's name?
an Industry entity
{
"name":"Fruits"
}
a Company entity
{
"name":"Apple",
"ticker":"AAPL",
}
20 / 46

an Industry entity
{
"https://data.example.com/ontology#industryName":"Fruits"
}
a Company entity
{
"https://data.example.com/ontology#companyName":"Apple",
"ticker":"AAPL",
}
21 / 46

a Company entity
{
"@context":{
"name":{"@id":"https://data.example.com/ontology#companyName"}
},
"name":"Apple",
"ticker":"AAPL",
}
22 / 46

contextualized data: typed values
a Company entity
{
"@context":{
"name":{"@id":"https://data.example.com/ontology#companyName"},
"ticker":{"@id":"https://data.example.com/ontology#ticker"},
"industry":{"@id":"https://data.example.com/ontology#industry"}
},
"name":"Apple",
"ticker":"AAPL",
}
23 / 46

contextualized data: default vocabulary
a Company entity
{
"@context":{
"@vocab":"https://data.example.com/ontology#",
"name":"companyName",
"ticker":{"@type":"Ticker"},
"industry":{"@type":"@id"}
},
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
"industry":"https://data.example.com/industry/q6po09"
}
24 / 46

JSON-LD
a Company entity
Content-Type:application/ld+json
{
"@context":{
},
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
}
25 / 46

not just yet another media type
is a standard
playground
in use
Google, BBC, Microsoft, Yandex, etc.
26 / 46

Contextualized data: external context
external context
$GEThttps://data.example.com/general-context.jsonld
{
"@context":{
}
}
a Company entity
Link:<https://data.example.com/context.jsonld>;rel="http://www.w3.org/ns/json-ld#context"
{
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
} 27 / 46

linking vs embedding
an Industry entity
{
"@context":{...},
"@type":"Industry",
"name":"Fruits"
}
a Company entity
{
"@context":{...},
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
}
28 / 46

linking vs embedding
a Company entity with its Industry entity
{
"@context":{...},
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
"industry":{
"@type":"Industry",
"name":"Fruits"
}
}
29 / 46

deep linking
a Company entity with its Industry entity
{
"@context":{...},
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
"industry":{
"@id":"#q6po09",
"@type":"Industry",
"name":"Fruits"
}
}
Now I could use <https://data.example.com/company/c34dap#q6po09>to speak
about the Industryreferenced from the document defining it.
30 / 46

inlining
a Company entity inlining the linked Industry entity
{
"@context":{...},
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
"industry":{
"@type":"Industry",
"name":"Fruits"
}
}
remarks
all (or part of) <https://data.example.com/industry/q6po09>'s state is
inlined
the Industry's identity+state is not under this Company's control
could even live on a different domain!
applications could decide to follow links to get authoritative state
31 / 46

Summary so far
started with
{
"id":"c34dap",
"name":"Apple",
"ticker":"AAPL",
"industry":"q6po09"
}
32 / 46

Summary so far
started with
{
"id":"c34dap",
"name":"Apple",
"ticker":"AAPL",
"industry":"q6po09"
}
ended up with something like
{
"@context":{...},
"@type":"Company",
"name":"Apple",
"ticker":"AAPL",
}
33 / 46

Immediate benefits
entities are referenced, embedded and linked together
we get for free provenance and data authority
attributes are disambiguated and can be interrogated
values are typed and can natively be links
vocabularies can be shared, reused and even checked
34 / 46

introducing LDP
Linked Data Platform
intersection of REST and RDF
being specced at W3C for the past 3 years
state-of-the-art of REST APIs
35 / 46

Container model
the usual
$GEThttps://data.example.com/company/
{
"contains":["https://data.example.com/company/c34dap",...]
}
becomes (introducing the LDP model)
Link:<http://www.w3.org/ns/ldp#BasicContainer>;rel="type"
{
"@context":{
"ldp":"http://www.w3.org/ns/ldp#",
"ldp:contains":{"@container":"@list","@type":"@id"}
},
"@type":["Companies","ldp:BasicContainer"],
"ldp:contains":[
"https://data.example.com/company/c34dap",
...
]
} 36 / 46

Container model + inlining
Container's state + inlined members
{
"@context":{...},
"@type":["Companies","ldp:BasicContainer"],
"ldp:contains":[
{
"@id":"https://data.example.com/company/c34dap",
"@type":"Company",
"ticker":"AAPL",
"name":"Apple",
"industry":{
"@type":"Industry",
"name":"Fruits"
}
},
...
]
}
37 / 46

enabling LDP interaction model
rel=type Link header
The "type" link relation can be used to indicate that the context
resource is an instance of the resource identified by the target
Internationalized Resource Identifier (IRI).
in LDP
The presence of this header asserts that the server complies with the
LDP specification's constraints on HTTP interactions with LDPRs, that
is it asserts that the resource has Etags, has an RDF representation,
and so on, which is not true of all Web resources served as RDF media
types.
38 / 46

LDP interaction model
resources
Resource (LDPR) ← RDF Source (LDPRS) ← Container (LDPC) ← Basic
Container (Basic Container)
affordance
advertised through rel=typeLink header, not Content-Type
a GET on a container (LDPC) returns its state (ie. its members)
resources (LDPR) are created by POSTing to the container
HTTP 201 Created + Locationheader
use DELETE to remove a member
use PUT to override the state of a member
use PATCH for partial updates
39 / 46

LDP Paging (Working Draft) [1/2]
HTTP 303 See Other
A 303 response to a GET request indicates that the origin server does
not have a representation of the target resource [...] the Location field
value refers to a resource that is descriptive of the target resource
also
server has control over the pagination mechanism
client sets preferences
semantics: snapshot, consistency, etc.
40 / 46

LDP Paging (Working Draft) [2/2]
use Link relations eg. rel='next'
303SeeOther
Location:https://data.example.com/company/?p=5YjF
$GEThttps://data.example.com/company/?p=5YjF
200OK
Link:<https://data.example.com/company/?p=AyOW>;rel="next"
{...}
Save a round-trip: HTTP 333 (being standardised)
41 / 46

services
make it discoverable
Link:<https://data.example.com/company/?>;rel="http://data.example.com/api#queryService"
Use Link relation again (not yet standardised)
example
$GEThttps://data.example.com/company/?offset=100&limit=50
42 / 46

ad-hoc service-oriented API [1/2]
$GEThttps://data.example.com/api/getCompaniesByIndustry?industryName="Fruits"
{
"@context":{...},
"results":[
{"@id":"https://data.example.com/company/c34dap",...},
...
]
}
domain aware
more capabilities
requires to read documentation
return resource URIs and use inlining when needed
43 / 46

ad-hoc service-oriented API [2/2]
microservices
going further
general purpose service-oriented API?
analytics
44 / 46

error handling
LDP servers MUST publish any constraints on LDP clients’ ability to
create or update LDPRs, by adding a Link header with
rel='describedby' [RFC5988] to all responses to requests which fail due
to violation of those constraints. [LDP 4.2.1.2]
so basically, HTTP 4xx + rel='describedby'Link header
use HTTP 400 for application-specific error [LDP ISSUE-98]
for machine readable errors, consider Problem Details for HTTP APIs [http-
problem-06]
45 / 46

to read
HTTP/REST
Web Client Programming with Perl
http://www.slideshare.net/RubenVerborgh/hypermedia-cannot-be-the-
engine
LDP
LDP 1.0 Primer (Editor's Draft)
LDP 1.0 (Editor's Draft)
RDF
http://www.w3.org/TR/2014/REC-turtle-20140225/
http://semanticweb.com/introduction-to-rdf_b17953
http://www.w3.org/TR/2012/REC-rdb-direct-mapping-20120927/
46 / 46

One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014

Recommended

Recommended

More Related Content

Viewers also liked

Viewers also liked (20)

Similar to One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014

Similar to One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014 (20)

More from Ippon

More from Ippon (11)

Recently uploaded

Recently uploaded (11)

One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014