1. Building REST and
Hypermedia APIs with PHP
International PHP Conference 2012 Tbilisi, Georgia
Wednesday, December 12, 12
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. REST
Representational State Transfer
Wednesday, December 12, 12
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 style
Wednesday, December 12, 12
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. 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. Analogy
Gothic Architecture
Wednesday, December 12, 12
8. Analogy
Georgian Church Architecture
Wednesday, December 12, 12
9. Analogy
Industrial Architecture
Wednesday, December 12, 12
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. 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
13. HTTP
The Hypertext Transfer Protocol (HTTP) is an
application-level protocol for distributed, collaborative,
hypertext information systems.
Hypertext Transfer Protocol RFC, HTTPbis
Wednesday, December 12, 12
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 1960s
Wednesday, December 12, 12
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. Hypermedia
Hypermedia simply extends the
notion of the text in hypertext by
including visual information, sound,
animation, and other forms of data.
George P. Landow
Wednesday, December 12, 12
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 1999
Wednesday, December 12, 12
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 1999
Wednesday, December 12, 12
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 2008
Wednesday, December 12, 12
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
22. The Story
Hey folks, we’ve created amazing photo sharing
service and we have an API! check it out:
http://service.org/photos
Wednesday, December 12, 12
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. 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"
parameter's 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. 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. 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 4
Wednesday, December 12, 12
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
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. Never encode action in URI
Wrong:
‣ /some/resource/delete
‣ /some/resource/update
Correct:
‣ DELETE /some/resource HTTP/1.1
‣ POST /some/resource
Wednesday, December 12, 12
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. 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. 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