Building REST and               Hypermedia APIs with PHP                         International PHP Conference 2012 Tbilisi...
About me    ‣ Ioseb Dzmanashvili    ‣ Software Architect at AzRy LLC    ‣ Teacher at Caucasus School of Technology    ‣ V8...
REST                             Representational State TransferWednesday, December 12, 12
What is REST?    ‣ It’s not a specification    ‣ It’s not a design pattern    ‣ It’s not... bla bla bla...    ‣ It’s an arc...
Architectural Style                                    Definition         An architectural style is a coordinated set of   ...
Architectural Style                                     Definition      An architectural style is a named         collectio...
Analogy                             Gothic ArchitectureWednesday, December 12, 12
Analogy                             Georgian Church ArchitectureWednesday, December 12, 12
Analogy                             Industrial ArchitectureWednesday, December 12, 12
REST Constraints   • Client Server: Separation of concerns is the principle behind the client-server       constraints. .....
Uniform Interface       By applying the software engineering principle of generality to       the component interface, the...
HypermediaWednesday, December 12, 12
HTTP         The Hypertext Transfer Protocol (HTTP) is an       application-level protocol for distributed, collaborative,...
Hypertext      By "hypertext", I mean non-sequential writing - text     that branches and allows choices to the reader, be...
Hypertext          An intriguing possibility, given a           large hypertext database with        typed links, is that ...
Hypermedia            Hypermedia simply extends the             notion of the text in hypertext by          including visu...
Hypermedia                     Hypermedia system, contains                      various types of relationships            ...
Hypermedia        Hypermedia: An application which            uses associative relationships        among information cont...
Hypertext        When I say hypertext, I mean the        simultaneous presentation of        information and controls such...
Examples of controls?       <!-- non visible link -->       <link rel="stylesheet" type="text/css" href="styles.css">     ...
Photo Service ExampleWednesday, December 12, 12
The Story                Hey folks, we’ve created amazing photo sharing                  service and we have an API! check...
Let’s try it                                  List of Photos                             GET /photos HTTP/1.1             ...
What’s this Link Header?                             Quotes from Web Linking spec(RFC5988)      • Link is a typed connecti...
Meaning of Relations                                 Quotes from specs      • The value "enclosure" signifies a related res...
Fetching Photo (Client A)                                                       Request                         GET /photo...
Client B Deletes Photo                                                            Request                       DELETE /ph...
Uploading Photo (Step 1)                       GET /photos/upload-form HTTP/1.1                                           ...
Uploading Photo (Step 2)                         POST /photos HTTP/1.1                         Host: service.org          ...
Quick advicesWednesday, December 12, 12
Do not use xml or json directly   Do not use these:                ‣      application/xml                ‣      applicatio...
Never encode action in URI   Wrong:                ‣      /some/resource/delete                ‣      /some/resource/updat...
Do not Abuse Protocol     Wrong:                HTTP/1.1 200 OK                Content-Type: application/json             ...
Do not Use URIs Directly                             HTTP/1.1 404 Not Found                             Content-Type: ... ...
Do not hardcode control                       information in your code       HTTP/1.1 200 OK       Content-Type: applicati...
Links in JSONWednesday, December 12, 12
And where is PHP?                               sorry... i lied :(Wednesday, December 12, 12
Questions?Wednesday, December 12, 12
Thank You!Wednesday, December 12, 12
Upcoming SlideShare
Loading in …5
×

Building REST and Hypermedia APIs with PHP

15,203 views

Published on

Adapted version for students

0 Comments
7 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
15,203
On SlideShare
0
From Embeds
0
Number of Embeds
14
Actions
Shares
0
Downloads
31
Comments
0
Likes
7
Embeds 0
No embeds

No notes for slide

Building REST and Hypermedia APIs with PHP

  1. 1. Building REST and Hypermedia APIs with PHP International PHP Conference 2012 Tbilisi, GeorgiaWednesday, December 12, 12
  2. 2. About me ‣ Ioseb Dzmanashvili ‣ Software Architect at AzRy LLC ‣ Teacher at Caucasus School of Technology ‣ V8 JavaScript engine contributor ‣ Author of uri_template PHP extension ‣ Author of Create-Form and Edit-Form link relation types (being RFCed now).Wednesday, December 12, 12
  3. 3. REST Representational State TransferWednesday, December 12, 12
  4. 4. What is REST? ‣ It’s not a specification ‣ It’s not a design pattern ‣ It’s not... bla bla bla... ‣ It’s an architectural styleWednesday, December 12, 12
  5. 5. Architectural Style Definition An architectural style is a coordinated set of architectural constraints that restricts the roles/features of architectural elements and the allowed relationships among those elements within any architecture that conforms to that style. Roy T. Fielding 2000 (quote from dissertation)Wednesday, December 12, 12
  6. 6. Architectural Style Definition An architectural style is a named collection of architectural design decisions that: 1) are applicable in a given development context; 2) constrain architectural decision that are specific to a particular system within that context; and 3) elicit beneficial qualities in each resulting system. Richard N. Taylor et al.Wednesday, December 12, 12
  7. 7. Analogy Gothic ArchitectureWednesday, December 12, 12
  8. 8. Analogy Georgian Church ArchitectureWednesday, December 12, 12
  9. 9. Analogy Industrial ArchitectureWednesday, December 12, 12
  10. 10. REST Constraints • Client Server: Separation of concerns is the principle behind the client-server constraints. ...Perhaps most significant to the Web, however, is that the separation allows the components to evolve independently. • Stateless: ...communication must be stateless in nature, ...such that each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server • Cache: The advantage of adding cache constraints is that they have the potential to partially or completely eliminate some interactions, improving efficiency, scalability, and user-perceived performance by reducing the average latency of a series of interactions. • Layered System: The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot "see" beyond the immediate layer with which they are interacting. • Code-On-Demand: (Optional constraint) • Uniform Interface: (To be continued)Wednesday, December 12, 12
  11. 11. Uniform Interface By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: • identification of resources; • manipulation of resources through representations; • self-descriptive messages; and, • hypermedia as the engine of application state.Wednesday, December 12, 12
  12. 12. HypermediaWednesday, December 12, 12
  13. 13. HTTP The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. Hypertext Transfer Protocol RFC, HTTPbisWednesday, December 12, 12
  14. 14. Hypertext By "hypertext", I mean non-sequential writing - text that branches and allows choices to the reader, best read at an interactive screen. As popularity conceived, this is a series of text chunks connected by links which offer the reader different pathways. Theodor Nelson 1960sWednesday, December 12, 12
  15. 15. Hypertext An intriguing possibility, given a large hypertext database with typed links, is that it allows some degree of automatic analysis. Tim Berners-Lee 1989, CERN (Initial WWW proposal)Wednesday, December 12, 12
  16. 16. Hypermedia Hypermedia simply extends the notion of the text in hypertext by including visual information, sound, animation, and other forms of data. George P. LandowWednesday, December 12, 12
  17. 17. Hypermedia Hypermedia system, contains various types of relationships between elements of information. Hypermedia allows these relationships to be instantiated as links which connect the various information elements, so that these links can be used to navigate within the information space. David Lowe, Wendy Hau 1999Wednesday, December 12, 12
  18. 18. Hypermedia Hypermedia: An application which uses associative relationships among information contained within multiple media data for the purpose of facilitating access to, and manipulation of, information encapsulated by the data David Lowe, Wendy Hau 1999Wednesday, December 12, 12
  19. 19. Hypertext When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions Roy T. Fielding 2008Wednesday, December 12, 12
  20. 20. Examples of controls? <!-- non visible link --> <link rel="stylesheet" type="text/css" href="styles.css"> <!-- outgoing link --> <a href="/post/1/author" rel="author">John Doe</a> <!-- embed link(transclusion) --> <img src="/logo.jpg" alt="IBM Logo"> <!-- templated link. produces: /search?q=term --> <form method="get" action="/search"> <label>Search: </label><input name="q"> </form> <!-- action link --> <form method="post" action="/posts" type="text/plain"> <textarea>Representational State Transfer</textarea> </form>Wednesday, December 12, 12
  21. 21. Photo Service ExampleWednesday, December 12, 12
  22. 22. The Story Hey folks, we’ve created amazing photo sharing service and we have an API! check it out: http://service.org/photosWednesday, December 12, 12
  23. 23. Let’s try it List of Photos GET /photos HTTP/1.1 Host: service.org 1 Request Response 2 HTTP/1.1 200 OK Link: </photos/1>; rel="enclosure"; type="image/jpg"; title= "Egypt", </photos/2>; rel="enclosure"; type="image/jpg"; title="Paris", </photos/3>; rel="enclosure"; type="image/jpg"; title="Tbilisi", </photos/upload-form>; rel="create-form"; title="Upload photo"Wednesday, December 12, 12
  24. 24. What’s this Link Header? Quotes from Web Linking spec(RFC5988) • Link is a typed connection between two resources that are identified by Internationalised Resource Identifiers (IRIs) • Links between resources need not be format specific; it can be useful to have typed links that are independent of their serialization. • The relation type of a link is conveyed in the "rel" parameters value. • The "type" parameter, when present, is a hint indicating what the media type of the result of dereferencing the link should be.Wednesday, December 12, 12
  25. 25. Meaning of Relations Quotes from specs • The value "enclosure" signifies a related resource that is potentially large and might require special handling. • The value "create-form" signifies a related resource where a submission form can be obtained.Wednesday, December 12, 12
  26. 26. Fetching Photo (Client A) Request GET /photos/1 HTTP/1.1 1 Host: service.org HTTP/1.1 200 OK Content-Type: image/jpeg Response Content-Length: 1000 Cache-Control: private, max-age=0 2 ETag: a32lasdf [PHOTO HERE] GET /photos/1 HTTP/1.1 Request 3 Host: service.org If-None-Match: a32lasdf Response HTTP/1.1 304 Not Modified 4Wednesday, December 12, 12
  27. 27. Client B Deletes Photo Request DELETE /photos/1 HTTP/1.1 1 Host: service.org Response HTTP/1.1 204 No Content 2 Client A Fetches it Again GET /photos/1 HTTP/1.1 Request 3 Host: service.org If-None-Match: a32lasdf HTTP/1.1 404 Not Found Response Content-Type: ... Content-Length: … 4 Link: </photos>; rel="index"; title="Photos", </photos/upload-form>; rel="create-form";Wednesday, December 12, 12
  28. 28. Uploading Photo (Step 1) GET /photos/upload-form HTTP/1.1 Request 1 Host: service.org HTTP/1.1 200 OK Content-Type: application/vnd.forms+json Content-Length: … Response { "method": "POST", 2 "action": "/photos", "content-type": [ "image/jpeg", "image/png", "image/gif", ] }Wednesday, December 12, 12
  29. 29. Uploading Photo (Step 2) POST /photos HTTP/1.1 Host: service.org Request Content-Type: image/jpeg 1 Content-Length: 3000 [PHOTO HERE] Response HTTP/1.1 202 Accepted Link: </photos/queue/e3ba8>; rel="monitor" 2 Retry-After: 10 Request GET /photos/queue/e3ba8 HTTP/1.1 3 Host: service.org Response HTTP/1.1 303 See Other Location: /photos/1234 4Wednesday, December 12, 12
  30. 30. Quick advicesWednesday, December 12, 12
  31. 31. Do not use xml or json directly Do not use these: ‣ application/xml ‣ application/json Instead try: ‣ application/atom+xml ‣ application/vnd.collection+json ‣ application/vnd.hal+json ‣ or design your own.Wednesday, December 12, 12
  32. 32. Never encode action in URI Wrong: ‣ /some/resource/delete ‣ /some/resource/update Correct: ‣ DELETE /some/resource HTTP/1.1 ‣ POST /some/resourceWednesday, December 12, 12
  33. 33. Do not Abuse Protocol Wrong: HTTP/1.1 200 OK Content-Type: application/json Content-Length: … {"error": { "code": 1234, "message": "Page not found" }} Correct: HTTP/1.1 404 Not Found Content-Type: application/json Content-Length: …Wednesday, December 12, 12
  34. 34. Do not Use URIs Directly HTTP/1.1 404 Not Found Content-Type: ... Content-Length: … Link: </photos>; rel="index"; title="Photos", </photos/upload-form>; rel="create-form"; HTTP/1.1 404 Not Found Content-Type: ... Content-Length: … Link: </photos>; rel="index"; title="Photos", </photos/upload-form>; rel="create-form";Wednesday, December 12, 12
  35. 35. Do not hardcode control information in your code HTTP/1.1 200 OK Content-Type: application/vnd.forms+json Content-Length: … { "method": "POST", "action": "/photos", "content-type": [ "image/jpeg", HTTP/1.1 200 OK ] Content-Type: application/vnd.forms+json } Content-Length: … { "method": "POST", "action": "/photos", "content-type": [ "image/jpeg", ] }Wednesday, December 12, 12
  36. 36. Links in JSONWednesday, December 12, 12
  37. 37. And where is PHP? sorry... i lied :(Wednesday, December 12, 12
  38. 38. Questions?Wednesday, December 12, 12
  39. 39. Thank You!Wednesday, December 12, 12

×