Your SlideShare is downloading. ×
0
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
One Web (API?) – Alexandre Bertails - Ippevent 10 juin 2014
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

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

1,171

Published on

Un simple site Web ne suffit plus : si je veux que les machines puissent comprendre et interagir avec mes données et pas seulement des pages HTML, je dois exposer une Web API. …

Un simple site Web ne suffit plus : si je veux que les machines puissent comprendre et interagir avec mes données et pas seulement des pages HTML, je dois exposer une Web API.

Or les styles, architectures et buzzwords sont variés (Web services, REST, hypermedia et maintenant HATEOAS, etc.) et les religions sont légion. Il a fallu de longues années pour que l’industrie et la communauté Web voient émerger de bonnes pratiques. L’heure est maintenant à la consolidation.

Cette présentation se veut une rétrospective sur l’évolution des Web APIs et plus généralement des données sur le Web. Je ferai une revue de l’état de l’art, illustrée par des exemples concrets et des conseils pratiques.

Le speaker : Alexandre est expert Linked Data à Pellucid Analytics. Auparavant au W3C. Code principalement en Scala et est intéressé par le Web, les données et les questions d’anonymat/vie privée sur le Web.

Published in: Internet, Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,171
On Slideshare
0
From Embeds
0
Number of Embeds
15
Actions
Shares
0
Downloads
23
Comments
0
Likes
2
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 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
  • 25. 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
  • 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
  • 42. 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
  • 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

×