SlideShare a Scribd company logo

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

Ippon, profile picture
Ippon

This document discusses using JSON and JSON-LD to represent data as linked data. It begins with simple examples of representing a company and industry as JSON objects. It then shows how to add identifiers, types, and links to represent the relationships between entities and conform to linked data principles. Finally, it introduces the Linked Data Platform (LDP) specification and how to structure data and interactions according to its constraints and affordances to build fully RESTful and linked data compliant APIs.

InternetTechnology
Related topics:
Web Services Overview
1 of 46
Downloaded 35 times
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
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 $HEADhttps://data.example.com/company/ 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 [...]. $HEADhttps://data.example.com/company/ Content-Type:application/json 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 Content-Type:application/json { "id":"q6po09", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "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 $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@id":"https://data.example.com/industry/q6po09", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@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 $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 17 / 46
what are we dealing with? an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "type":"Industry", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "type":"Company", "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 18 / 46
@type+ URL an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Industry"}, "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 19 / 46
disambiguating attributes [1/3] How to distinguish an industry's name from a company's name? an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Industry"}, "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 20 / 46
disambiguating attributes [2/3] How to distinguish an industry's name from a company's name? an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Industry"}, "https://data.example.com/ontology#industryName":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Company"}, "https://data.example.com/ontology#companyName":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 21 / 46
disambiguating attributes [3/3] How to distinguish an industry's name from a company's name? a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@context":{ "name":{"@id":"https://data.example.com/ontology#companyName"} }, "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 22 / 46
contextualized data: typed values a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@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"} }, "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 23 / 46
contextualized data: default vocabulary a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@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 $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@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" } 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 Content-Type:application/ld+json { "@context":{ "@vocab":"https://data.example.com/ontology#", "name":"companyName", "ticker":{"@type":"Ticker"}, "industry":{"@type":"@id"} } } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json Link:<https://data.example.com/context.jsonld>;rel="http://www.w3.org/ns/json-ld#context" { "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":"https://data.example.com/industry/q6po09" } 27 / 46
linking vs embedding an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/ld+json { "@context":{...}, "@type":"Industry", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":"https://data.example.com/industry/q6po09" } 28 / 46
linking vs embedding a Company entity with its Industry entity $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":{ "@type":"Industry", "name":"Fruits" } } 29 / 46
deep linking a Company entity with its Industry entity $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@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 $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":{ "@id":"https://data.example.com/industry/q6po09", "@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 $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "id":"c34dap", "name":"Apple", "ticker":"AAPL", "industry":"q6po09" } 32 / 46
Summary so far started with $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "id":"c34dap", "name":"Apple", "ticker":"AAPL", "industry":"q6po09" } ended up with something like $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":"https://data.example.com/industry/q6po09" } 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/ Content-Type:application/json { "contains":["https://data.example.com/company/c34dap",...] } becomes (introducing the LDP model) $GEThttps://data.example.com/company/ Content-Type:application/ld+json 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 $GEThttps://data.example.com/company/ Content-Type:application/ld+json Link:<http://www.w3.org/ns/ldp#BasicContainer>;rel="type" { "@context":{...}, "@type":["Companies","ldp:BasicContainer"], "ldp:contains":[ { "@id":"https://data.example.com/company/c34dap", "@type":"Company", "ticker":"AAPL", "name":"Apple", "industry":{ "@id":"https://data.example.com/industry/q6po09", "@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. $HEADhttps://data.example.com/company/ Content-Type:application/ld+json Link:<http://www.w3.org/ns/ldp#BasicContainer>;rel="type" 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' $GEThttps://data.example.com/company/ 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" Content-Type:application/ld+json {...} Save a round-trip: HTTP 333 (being standardised) 41 / 46
services make it discoverable $HEADhttps://data.example.com/company/ Content-Type:application/ld+json 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" Content-Type:application/ld+json { "@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

More Related Content

PDF
Isa case study_how_to_describe_organizations_in_rdf_core_business_vocabulary
Semic.eu
 
PPTX
REST Architecture with use case and example
Shailesh singh
 
PPTX
Smartlogic, Semaphore and Semantically Enhanced Search – For “Discovery”
VOGIN-academie
 
PPTX
EOSC Provider and Resource Profiles Tutorial
EOSCEuropeanOpenScie
 
DOCX
Entity linking with a knowledge base issues,
Nexgen Technology
 
PPTX
Mapping Corporate Networks With OpenCorporates
Tony Hirst
 
PDF
School of Data - mapping company networks
Tony Hirst
 
PPTX
FHIR Profiles
David Hay
 
Isa case study_how_to_describe_organizations_in_rdf_core_business_vocabulary
Semic.eu
 
REST Architecture with use case and example
Shailesh singh
 
Smartlogic, Semaphore and Semantically Enhanced Search – For “Discovery”
VOGIN-academie
 
EOSC Provider and Resource Profiles Tutorial
EOSCEuropeanOpenScie
 
Entity linking with a knowledge base issues,
Nexgen Technology
 
Mapping Corporate Networks With OpenCorporates
Tony Hirst
 
School of Data - mapping company networks
Tony Hirst
 
FHIR Profiles
David Hay
 

Viewers also liked (20)

PDF
Multi criteria queries on a cassandra application
Ippon
 
PDF
Quoi de neuf pour JHipster en 2016
Ippon
 
PDF
Cassandra Java Driver : vers Cassandra 1.2 et au-delà
Ippon
 
PPTX
Système d’Information à l’Apec : un nouveau coeur de métier mis en place avec...
Ippon
 
PDF
Démystifions le machine learning avec spark par David Martin pour le Salon B...
Ippon
 
PDF
Atelier TDD (Test Driven Development)
Ippon
 
PDF
Formation Gratuite Total Tests par les experts Java Ippon
Ippon
 
PDF
Realtime Web avec Akka, Kafka, Spark et Mesos - Devoxx Paris 2014
Ippon
 
PDF
Agilité, n’oublions pas les valeurs
Ippon
 
PDF
Formation Spring Avancé gratuite par Ippon 2014
Ippon
 
PDF
Web API & Cache, the HTTP way - Ippevent 10 Juin 2014
Ippon
 
PDF
Formation Usine Logicielle gratuite par Ippon 2014
Ippon
 
PDF
Formation html5 CSS3 offerte par ippon 2014
Ippon
 
PDF
Formation JPA Avancé / Hibernate gratuite par Ippon 2014
Ippon
 
PDF
Formation GIT gratuite par ippon 2014
Ippon
 
PDF
JPA avec Cassandra, grâce à Achilles
Ippon
 
PDF
Nouveau look pour une nouvelle vie : HTML5, Spring, NoSQL et Mobile
Ippon
 
PPTX
La gouvernance de l'information est une affaire de changement - Conférence SE...
Perrein Jean-Pascal
 
PPT
Offre 3org Conseil sur la gouvernance et la gestion de l'information d'entrep...
Perrein Jean-Pascal
 
PDF
2015 01-camoai transformation-numerique_groupe_offre
Jean-Marc Touzard
 
Multi criteria queries on a cassandra application
Ippon
 
Quoi de neuf pour JHipster en 2016
Ippon
 
Cassandra Java Driver : vers Cassandra 1.2 et au-delà
Ippon
 
Système d’Information à l’Apec : un nouveau coeur de métier mis en place avec...
Ippon
 
Démystifions le machine learning avec spark par David Martin pour le Salon B...
Ippon
 
Atelier TDD (Test Driven Development)
Ippon
 
Formation Gratuite Total Tests par les experts Java Ippon
Ippon
 
Realtime Web avec Akka, Kafka, Spark et Mesos - Devoxx Paris 2014
Ippon
 
Agilité, n’oublions pas les valeurs
Ippon
 
Formation Spring Avancé gratuite par Ippon 2014
Ippon
 
Web API & Cache, the HTTP way - Ippevent 10 Juin 2014
Ippon
 
Formation Usine Logicielle gratuite par Ippon 2014
Ippon
 
Formation html5 CSS3 offerte par ippon 2014
Ippon
 
Formation JPA Avancé / Hibernate gratuite par Ippon 2014
Ippon
 
Formation GIT gratuite par ippon 2014
Ippon
 
JPA avec Cassandra, grâce à Achilles
Ippon
 
Nouveau look pour une nouvelle vie : HTML5, Spring, NoSQL et Mobile
Ippon
 
La gouvernance de l'information est une affaire de changement - Conférence SE...
Perrein Jean-Pascal
 
Offre 3org Conseil sur la gouvernance et la gestion de l'information d'entrep...
Perrein Jean-Pascal
 
2015 01-camoai transformation-numerique_groupe_offre
Jean-Marc Touzard
 
Ad

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

PPTX
Approaches to machine actionable links
Stephen Richard
 
PDF
Hypermedia APIs and HATEOAS
Vladimir Tsukur
 
PPTX
Introduction to Hydra
Alejandro Inestal
 
ODP
Semantic web technologies applied to bioinformatics and laboratory data manag...
Toni Hermoso Pulido
 
PDF
REST based API
ijtsrd
 
PDF
Open Calais
ymark
 
PDF
API Management and software services.pdf
Prowess Software Services Inc
 
PDF
Whitepaper - A Guide to API Design Best Practices
Prowess Software Services Inc
 
PDF
Whitepaper-API-Design-Best-Practices. Prowess software services
Prowess Software Services Inc
 
ODP
DC-2008 Tutorial 3 - Dublin Core and other metadata schemas
Mikael Nilsson
 
PPT
Modified REST Presentation
Alexandros Marinos
 
PPT
Elucidating the Mashup Hype: Definition, Challenges, Methodical Guide and Too...
dflejter
 
PPTX
Mastering-ASPNET-Web-API-and-RESTful-Patterns.pptx
keshabregmi1
 
PDF
Building social and RESTful frameworks
brendonschwartz
 
PDF
Hypermedia APIs and HATEOAS / Wix Engineering
Vladimir Tsukur
 
PDF
Standard Web APIs for Multidisciplinary Collaboration
Axel Reichwein
 
PPTX
LinkML Intro July 2022.pptx PLEASE VIEW THIS ON ZENODO
Chris Mungall
 
PPT
REST Presentation
Alexandros Marinos
 
PDF
Linking Media and Data using Apache Marmotta (LIME workshop keynote)
LinkedTV
 
PPT
OpenSearch
hchen1
 
Approaches to machine actionable links
Stephen Richard
 
Hypermedia APIs and HATEOAS
Vladimir Tsukur
 
Introduction to Hydra
Alejandro Inestal
 
Semantic web technologies applied to bioinformatics and laboratory data manag...
Toni Hermoso Pulido
 
REST based API
ijtsrd
 
Open Calais
ymark
 
API Management and software services.pdf
Prowess Software Services Inc
 
Whitepaper - A Guide to API Design Best Practices
Prowess Software Services Inc
 
Whitepaper-API-Design-Best-Practices. Prowess software services
Prowess Software Services Inc
 
DC-2008 Tutorial 3 - Dublin Core and other metadata schemas
Mikael Nilsson
 
Modified REST Presentation
Alexandros Marinos
 
Elucidating the Mashup Hype: Definition, Challenges, Methodical Guide and Too...
dflejter
 
Mastering-ASPNET-Web-API-and-RESTful-Patterns.pptx
keshabregmi1
 
Building social and RESTful frameworks
brendonschwartz
 
Hypermedia APIs and HATEOAS / Wix Engineering
Vladimir Tsukur
 
Standard Web APIs for Multidisciplinary Collaboration
Axel Reichwein
 
LinkML Intro July 2022.pptx PLEASE VIEW THIS ON ZENODO
Chris Mungall
 
REST Presentation
Alexandros Marinos
 
Linking Media and Data using Apache Marmotta (LIME workshop keynote)
LinkedTV
 
OpenSearch
hchen1
 
Ad

More from Ippon (11)

PDF
Offre 2015 numeriq_ippon
Ippon
 
KEY
CDI par la pratique
Ippon
 
PDF
Hibernate vs le_cloud_computing
Ippon
 
PDF
Stateful is beautiful
Ippon
 
PDF
Présentation Ippon DGA Liferay Symposium 2011
Ippon
 
PDF
Scrum et forfait
Ippon
 
PDF
Mule ESB Summit 2010 avec Ippon
Ippon
 
PDF
Présentation du retour d'expérience sur Git
Ippon
 
PDF
Présentation Rex GWT 2.0
Ippon
 
PDF
Presentation Rex Methodes Agiles
Ippon
 
PDF
Seminaire Portail Open Source
Ippon
 
Offre 2015 numeriq_ippon
Ippon
 
CDI par la pratique
Ippon
 
Hibernate vs le_cloud_computing
Ippon
 
Stateful is beautiful
Ippon
 
Présentation Ippon DGA Liferay Symposium 2011
Ippon
 
Scrum et forfait
Ippon
 
Mule ESB Summit 2010 avec Ippon
Ippon
 
Présentation du retour d'expérience sur Git
Ippon
 
Présentation Rex GWT 2.0
Ippon
 
Presentation Rex Methodes Agiles
Ippon
 
Seminaire Portail Open Source
Ippon
 

Recently uploaded (20)

PDF
Tenda Login Guide: Access Your Router in 5 Easy Steps
tendawifi16
 
PPTX
artificial intelligence overview of it and more
yafotin445
 
PPTX
SAP Ariba Sourcing PPT for learning material
NKKumar16
 
PDF
Vigrab.top – Online Tool for Downloading and Converting Social Media Videos a...
Vigrab Top
 
PPTX
Funds Management Learning Material for Beg
NKKumar16
 
PPTX
522797556-Unit-2-Temperature-measurement-1-1.pptx
msar8888
 
PPTX
introduction about ICD -10 & ICD-11 ppt.pptx
naveenithkrishnan
 
PDF
Decoding a Decade: 10 Years of Applied CTI Discipline
Andreas Sfakianakis
 
PPTX
Digital Literacy And Online Safety on internet
riksa rifqi
 
PPT
Design_with_Watersergyerge45hrbgre4top (1).ppt
DiogoRibeiro730590
 
PDF
Smart Home Technology for Health Monitoring (www.kiu.ac.ug)
publication11
 
PPTX
Mathew Digital SEO Checklist Guidlines 2025
Mathew Digital
 
PDF
💰 𝐔𝐊𝐓𝐈 𝐊𝐄𝐌𝐄𝐍𝐀𝐍𝐆𝐀𝐍 𝐊𝐈𝐏𝐄𝐑𝟒𝐃 𝐇𝐀𝐑𝐈 𝐈𝐍𝐈 𝟐𝟎𝟐𝟓 💰
GRAB
 
PDF
Exploring VPS Hosting Trends for SMBs in 2025
Liquid Web
 
PPTX
Introuction about WHO-FIC in ICD-10.pptx
naveenithkrishnan
 
PDF
Slides PDF The World Game (s) Eco Economic Epochs.pdf
Steven McGee
 
PPTX
Introduction to Information and Communication Technology
AkmadArzieAyao1
 
DOCX
Unit-3 cyber security network security of internet system
shivangisharma636228
 
PDF
Unit-1 introduction to cyber security discuss about how to secure a system
shivangisharma636228
 
PDF
SASE Traffic Flow - ZTNA Connector-1.pdf
mackwell7777
 
Tenda Login Guide: Access Your Router in 5 Easy Steps
tendawifi16
 
artificial intelligence overview of it and more
yafotin445
 
SAP Ariba Sourcing PPT for learning material
NKKumar16
 
Vigrab.top – Online Tool for Downloading and Converting Social Media Videos a...
Vigrab Top
 
Funds Management Learning Material for Beg
NKKumar16
 
522797556-Unit-2-Temperature-measurement-1-1.pptx
msar8888
 
introduction about ICD -10 & ICD-11 ppt.pptx
naveenithkrishnan
 
Decoding a Decade: 10 Years of Applied CTI Discipline
Andreas Sfakianakis
 
Digital Literacy And Online Safety on internet
riksa rifqi
 
Design_with_Watersergyerge45hrbgre4top (1).ppt
DiogoRibeiro730590
 
Smart Home Technology for Health Monitoring (www.kiu.ac.ug)
publication11
 
Mathew Digital SEO Checklist Guidlines 2025
Mathew Digital
 
💰 𝐔𝐊𝐓𝐈 𝐊𝐄𝐌𝐄𝐍𝐀𝐍𝐆𝐀𝐍 𝐊𝐈𝐏𝐄𝐑𝟒𝐃 𝐇𝐀𝐑𝐈 𝐈𝐍𝐈 𝟐𝟎𝟐𝟓 💰
GRAB
 
Exploring VPS Hosting Trends for SMBs in 2025
Liquid Web
 
Introuction about WHO-FIC in ICD-10.pptx
naveenithkrishnan
 
Slides PDF The World Game (s) Eco Economic Epochs.pdf
Steven McGee
 
Introduction to Information and Communication Technology
AkmadArzieAyao1
 
Unit-3 cyber security network security of internet system
shivangisharma636228
 
Unit-1 introduction to cyber security discuss about how to secure a system
shivangisharma636228
 
SASE Traffic Flow - ZTNA Connector-1.pdf
mackwell7777
 

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

  • 1. Web APIs Alexandre Bertails, Pellucid Analytics @bertails 1 / 46
  • 2. Web APIs Who are the users of my API? What do they do with it? How will they interact with it? 2 / 46
  • 3. 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
  • 4. HTTP, back to the basics resources representations semantics 4 / 46
  • 5. 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
  • 6. 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
  • 7. IANA registry for media types IANA registry for Media Types Name Template Reference json application/json [RFC7158] 7 / 46
  • 8. 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
  • 9. 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
  • 10. extending media type semantics what wouldthe RESTafarian do? probably use a vendor specific media type $HEADhttps://data.example.com/company/ Content-Type:application/vnd.example.company+json 10 / 46
  • 11. 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 [...]. $HEADhttps://data.example.com/company/ Content-Type:application/json Link:<https://data.example.com/ontology#Company>;rel="profile" 11 / 46
  • 12. 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
  • 13. 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
  • 14. data patterns in JSON encodings links types disambiguating schemas Let's make JSON a hypermedia format :-) 14 / 46
  • 15. a 1st version an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "id":"q6po09", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "id":"c34dap", "name":"Apple", "ticker":"AAPL", "industry":"q6po09" } documentation probably available at something like https://data.example.com/api/documentation 15 / 46
  • 16. things, not String-s an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@id":"https://data.example.com/industry/q6po09", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@id":"https://data.example.com/company/c34dap", "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 16 / 46
  • 17. this is its own @id an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 17 / 46
  • 18. what are we dealing with? an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "type":"Industry", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "type":"Company", "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 18 / 46
  • 19. @type+ URL an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Industry"}, "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 19 / 46
  • 20. disambiguating attributes [1/3] How to distinguish an industry's name from a company's name? an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Industry"}, "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 20 / 46
  • 21. disambiguating attributes [2/3] How to distinguish an industry's name from a company's name? an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Industry"}, "https://data.example.com/ontology#industryName":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@type":{"@id":"https://data.example.com/ontology#Company"}, "https://data.example.com/ontology#companyName":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 21 / 46
  • 22. disambiguating attributes [3/3] How to distinguish an industry's name from a company's name? a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@context":{ "name":{"@id":"https://data.example.com/ontology#companyName"} }, "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 22 / 46
  • 23. contextualized data: typed values a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@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"} }, "@type":{"@id":"https://data.example.com/ontology#Company"}, "name":"Apple", "ticker":"AAPL", "industry":{"@id":"https://data.example.com/industry/q6po09"} } 23 / 46
  • 24. contextualized data: default vocabulary a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "@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
  • 26. not just yet another media type is a standard playground in use Google, BBC, Microsoft, Yandex, etc. 26 / 46
  • 27. Contextualized data: external context external context $GEThttps://data.example.com/general-context.jsonld Content-Type:application/ld+json { "@context":{ "@vocab":"https://data.example.com/ontology#", "name":"companyName", "ticker":{"@type":"Ticker"}, "industry":{"@type":"@id"} } } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/json Link:<https://data.example.com/context.jsonld>;rel="http://www.w3.org/ns/json-ld#context" { "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":"https://data.example.com/industry/q6po09" } 27 / 46
  • 28. linking vs embedding an Industry entity $GEThttps://data.example.com/industry/q6po09 Content-Type:application/ld+json { "@context":{...}, "@type":"Industry", "name":"Fruits" } a Company entity $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":"https://data.example.com/industry/q6po09" } 28 / 46
  • 29. linking vs embedding a Company entity with its Industry entity $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":{ "@type":"Industry", "name":"Fruits" } } 29 / 46
  • 30. deep linking a Company entity with its Industry entity $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@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
  • 31. inlining a Company entity inlining the linked Industry entity $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":{ "@id":"https://data.example.com/industry/q6po09", "@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
  • 32. Summary so far started with $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "id":"c34dap", "name":"Apple", "ticker":"AAPL", "industry":"q6po09" } 32 / 46
  • 33. Summary so far started with $GEThttps://data.example.com/company/c34dap Content-Type:application/json { "id":"c34dap", "name":"Apple", "ticker":"AAPL", "industry":"q6po09" } ended up with something like $GEThttps://data.example.com/company/c34dap Content-Type:application/ld+json { "@context":{...}, "@type":"Company", "name":"Apple", "ticker":"AAPL", "industry":"https://data.example.com/industry/q6po09" } 33 / 46
  • 34. 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
  • 35. 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
  • 36. Container model the usual $GEThttps://data.example.com/company/ Content-Type:application/json { "contains":["https://data.example.com/company/c34dap",...] } becomes (introducing the LDP model) $GEThttps://data.example.com/company/ Content-Type:application/ld+json 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
  • 37. Container model + inlining Container's state + inlined members $GEThttps://data.example.com/company/ Content-Type:application/ld+json Link:<http://www.w3.org/ns/ldp#BasicContainer>;rel="type" { "@context":{...}, "@type":["Companies","ldp:BasicContainer"], "ldp:contains":[ { "@id":"https://data.example.com/company/c34dap", "@type":"Company", "ticker":"AAPL", "name":"Apple", "industry":{ "@id":"https://data.example.com/industry/q6po09", "@type":"Industry", "name":"Fruits" } }, ... ] } 37 / 46
  • 38. 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. $HEADhttps://data.example.com/company/ Content-Type:application/ld+json Link:<http://www.w3.org/ns/ldp#BasicContainer>;rel="type" 38 / 46
  • 39. 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
  • 40. 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
  • 41. LDP Paging (Working Draft) [2/2] use Link relations eg. rel='next' $GEThttps://data.example.com/company/ 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" Content-Type:application/ld+json {...} Save a round-trip: HTTP 333 (being standardised) 41 / 46
  • 43. ad-hoc service-oriented API [1/2] $GEThttps://data.example.com/api/getCompaniesByIndustry?industryName="Fruits" Content-Type:application/ld+json { "@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
  • 44. ad-hoc service-oriented API [2/2] microservices going further general purpose service-oriented API? analytics 44 / 46
  • 45. 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
  • 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