Building REST and Hypermedia APIs with PHP

Building REST and
Hypermedia APIs with PHP

International PHP Conference 2012 Tbilisi, Georgia
Wednesday, December 12, 12

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).


REST
Representational State Transfer


What is REST?

‣ It’s not a speciﬁcation
‣ It’s not a design pattern
‣ It’s not... bla bla bla...
‣ It’s an architectural style


Architectural Style
Deﬁnition

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)


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.


Analogy
Gothic Architecture


Analogy
Georgian Church Architecture


Analogy
Industrial Architecture


REST Constraints
• Client Server: Separation of concerns is the principle behind the client-server
constraints. ...Perhaps most signiﬁcant 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 efﬁciency, 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)

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.

Hypermedia


HTTP

The Hypertext Transfer Protocol (HTTP) is an
application-level protocol for distributed, collaborative,
hypertext information systems.

Hypertext Transfer Protocol RFC, HTTPbis


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


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)


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


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


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


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


Examples of controls?


<link rel="stylesheet" type="text/css" href="styles.css">


<a href="/post/1/author" rel="author">John Doe</a>


<img src="/logo.jpg" alt="IBM Logo">


<form method="get" action="/search">
<label>Search: </label><input name="q">
</form>


<form method="post" action="/posts" type="text/plain">
<textarea>Representational State Transfer</textarea>
</form>

Photo Service Example


The Story

Hey folks, we’ve created amazing photo sharing
service and we have an API! check it out:
http://service.org/photos


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"


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.

Meaning of Relations
Quotes from specs

• The value "enclosure" signiﬁes a related resource
that is potentially large and might require special
handling.

• The value "create-form" signiﬁes a related
resource where a submission form can be obtained.


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

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";


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",
]
}


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
4

Quick advices


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.

Never encode action in URI
Wrong:

‣ /some/resource/delete

‣ /some/resource/update

Correct:

‣ DELETE /some/resource HTTP/1.1

‣ POST /some/resource


Do not Abuse Protocol

Wrong:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: …

{"error": {
"code": 1234,
"message": "Page not found"
}}

Correct:
Content-Type: application/json
Content-Length: …


Do not Use URIs Directly

Content-Type: ...
Content-Length: …

Content-Type: ...
Content-Length: …


Do not hardcode control
information in your code
HTTP/1.1 200 OK
Content-Type: application/vnd.forms+json
Content-Length: …

{
"method": "POST",
"content-type": [
"image/jpeg", HTTP/1.1 200 OK
] Content-Type: application/vnd.forms+json
} Content-Length: …

{
"method": "POST",
"content-type": [
"image/jpeg",
]
}


Links in JSON


And where is PHP?

sorry... i lied :(


Questions?


Thank You!


Building REST and Hypermedia APIs with PHP

More Related Content

What's hot

Similar to Building REST and Hypermedia APIs with PHP

Building REST and Hypermedia APIs with PHP