Share
Embed
Demystifying the REST API
Are you confused by REST APIs? Can't tell a PUT from a POST? No idea what a non-idempotent operation is?
Despite their ubiquity, the details of what makes an API RESTful are often lost even on experienced developers. We'll cover the basics of the HTTP protocol that drives most REST services, break down the lingo, and clear up some misconceptions about this powerful and popular methodology.
Samantha Quiñones
January 18, 2014
Transcript
95 slides
-
About Me Samantha Quiñones SW Architect & Lead Developer at
POLITICO.com Follow me: @ieatkillerbees -
What is REST? (and why am I talking about it?)
REpresentational State Transfer An architectural style that describes a set of rules for delivering content over an open network -
Nothing is more easy than to reduce this mass to
one quarter of its bulk. You know that curious cellular matter which constitutes the elementary tissues of vegetable? This substance is found quite pure in many bodies, especially in cotton, which is nothing more than the down of the seeds of the cotton plant. Now cotton, combined with cold nitric acid, become transformed into a substance eminently insoluble, combustible, and explosive. It was first discovered in 1832, by Braconnot, a French chemist, who called it xyloidine. In 1838 another Frenchman, Pelouze, investigated its different properties, and finally, in 1846, Schonbein, professor of chemistry at Bale, proposed its employment for purposes of war. This powder, now called pyroxyle, or fulminating cotton, is prepared with great facility by simply plunging cotton for fifteen minutes in nitric acid, then washing it in water, then drying it, and it is ready for use. -
Nothing is more easy than to reduce this mass to
one quarter of its bulk. You know that curious cellular matter which constitutes the elementary tissues of vegetable? This substance is found quite pure in many bodies, especially in cotton, which is nothing more than the down of the seeds of the cotton plant. Now cotton, combined with cold nitric acid, become transformed into a substance eminently insoluble, combustible, and explosive. It was first discovered in 1832, by Braconnot, a French chemist, who called it xyloidine. In 1838 another Frenchman, Pelouze, investigated its different properties, and finally, in 1846, Schonbein, professor of chemistry at Bale, proposed its employment for purposes of war. This powder, now called pyroxyle, or fulminating cotton, is prepared with great facility by simply plunging cotton for fifteen minutes in nitric acid, then washing it in water, then drying it, and it is ready for use. -
Ordo ab chao REST is a set of constraints designed
to bring order of the chaos of free-form hypermedia The young web was extremely disordered Fielding envisioned the web as a system that could be moulded by carefully applying constraints -
Null Style The Null Style describes an empty set of
constraints There are no boundaries and no structure -
Client-Server Architecture The system is divided in to clients and
servers Servers store hypermedia resources Clients manage the display and caching of resources -
Implicit State Requesting the “next” resource in a collection requires
the server to know what you asked for last This information may need to be shared among many servers in a cluster This information may be lost due to server errors Gief next cat pic pls! -
Explicit State The client is better suited to choose what
state is important Server failures do not cause loss of state Improved performance and reliability Load-balancing becomes trivial Gief cat pic #3427 pls! -
Debugging State Stinks All requests contain all the context needed
to execute them Simplifies debugging Makes traffic “replayable” -
Cacheable Requests Transmitting state with each request increases overhead Allowing
clients to cache responses can drastically reduce the number required requests -
Best Parsed By… Resources can carry an expiration time Clients
can wait until a resource expires before requesting it again -
Resources Resources are abstractions of data with a globally unique
identifier http://i.imgur.com/eqTIb.jpg -
Representations { name: “Kitty McAwesome”, awesome:
true, cute: “very”, image_uri: “http://i.imgur.com/eqTIb.jpg” } -
Self-Contained Requests GET /eqTIb.jpg HTTP/1.1 Host: i.imgur.com If-‐Modified-‐Since:
Fri, 02 Dec 2011 19:47:21 GMT -
HATEOAS GET /events/201 ! 200 OK <event>
<id>201</id> <name>Summer Bridge Party</name> <organizer> <name>David Wildstein</name> <email>[email protected]</email> <link rel=”self” href=”/organizers/42” /> </organizer> <link rel=”self” href=”/events/201” /> <link rel=”attendees” href=”/events/201/attendees” /> </event> -
JSON & Hypermedia GET /events/201 ! 200 OK
{ id: 201, name: “Summer Bridge Party”, organizer: { name: “David Wildstein”, email: “[email protected]” } } -
JSON Hyper-Schema Extension of json-schema that allows for hypermedia descriptions
http://json-schema.org -
Hypertext Application Language (HAL) Proposed standard that extends the JSON
type with hypermedia data application/json+hal Small but growing acceptance -
HAL GET /events/201 ! 200 OK {
“id”: 201, “name”: “Summer Bridge Party”, “_links”: { “self”: { “href”: “/events/201” }, }, “_embedded”: { “organizer”: { “_links”: { “self”: { “href”: “/organizers/42” } } } } -
Layered System Any two layers can only see one another
Client > Proxy > Load Balancer > Server -
Batteries Included Representations can include executable code Allows clients to
have extended functionality without updating multiple code bases JavaScript, Flash, Java Applets -
“A resource (R) is a temporally varying membership function MR(t),
which for time t maps to a set of entities, or values, which are equivalent.” –Roy Fielding Resources -
Resources An abstraction of some entity, or a collection of
entities, that we can identify by name. http://i.imgur.com/eqTIb.jpg “all accounts created on October 12th” “the most recent 100 tweets containing the string ‘#redwedding’” -
Resources On the web, we use Uniform Resource Identifiers http://i.imgur.com/eqTIb.jpg
Resource named eqTIb.jpg available via HTTP from i.imgur.com -
Representations In order to interact with a resource, we use
a representation Representations contain data and metadata -
Representations GET /accounts/42 ! 200 OK Content-‐Type: application/json+hal
! { account_id: 42, account_name: “Samantha Quiñones”, account_status: “awesome” _links: { self: { href: “/accounts/42” } } } -
Representations Resources are abstract, representations are concrete Representations are the
actual bytes that are transferred between clients and servers, including metadata Often called a “file,” “document,” or “entity” -
Control Data Control data is extra information used by the
client and server to coordinate Cache control information Parameters Content-type negotiation -
HyperText Transfer Protocol Version 0.9 (1991), Version 1.0 (1996) Current
Version 1.1 defined by RFC 2616 Nine methods, ~40 response codes -
Request-Response Cycle Client opens a connection to a server Client
sends a request containing a method, a resource, and optionally meta/control data Server responds with a status code and a representation of the requested resource, along with meta/control data -
Methods “Safe” methods: GET, HEAD, TRACE, OPTIONS “Unsafe” methods: PUT,
POST, DELETE, PATCH “Control” method: CONNECT -
! $app-‐>get("/foo/{id}", function (Request $request, Application $app, $id) {
if ( ! $app['db']-‐>has($id)) { throw new HttpNotFoundException(); } ! return new Response($app['db']-‐>get($id)); }); GET -
HEAD, OPTIONS, and TRACE HEAD requests the headers that would
have been sent with the equivalent GET request OPTIONS requests the HTTP methods that the server supports for a given resource TRACE requests the server echo back the request. This is useful for determining if an intermediate server is altering a requests in flight. -
DELETE $app-‐>delete("/foo/{id}", function (Request $request, Application $app, $id) {
if ( ! $app['db']-‐>has($id)) { throw new HttpNotFoundException(); } ! $app['db']-‐>delete($id); ! return new Response("", Response::HTTP_NO_CONTENT); }); -
PUT Asks the server to store a resource at a
specific URI, overwriting it if it already exists -
PUT $app-‐>put("/foo/{id}", function (Request $request, Application $app, $id) {
if ($app['db']-‐>has($id)) { $app['db']-‐>update($id, $request-‐>getBody()); return new Response("", Response::HTTP_OK) } ! $app['db']-‐>insertWithId($id, $request-‐>getBody()); return new Response("", Response::HTTP_CREATED); }); -
POST Asks the server to store a resource as a
sub- resource of a specified resource or collection -
POST $app-‐>post("/foo", function (Request $request, Application $app) {
$newId = $app['db']-‐>insert($request-‐>getBody()); $responseData = array( "_links" => array( "self" => array( "href" => "/foo/$newId" ) ) ); return new Response($responseData, Response::HTTP_CREATED); }); -
POST is Versatile Annotate existing resources Posting to a message
board, mailing list, etc Providing a block of data to a data-handling process Appending to a database -
PUT vs POST PUT creates or replaces a resources with
a known identifier POST creates a sub-resource of an existing resource or collection -
Idempotence When the result of an operation remains the same
no matter how many times the operation is performed, the operation is “idempotent” -
Idempotence Safe & Idempotent • GET • TRACE • HEAD
• OPTIONS Unsafe & Idempotent • PUT • DELETE ! Unsafe & Non-Idempotent • POST • PATCH -
DELETE is Idempotent Deleting a resource causes the server to
return a status code of 204 (NO CONTENT) Subsequent DELETE requests will cause the server to return a status code of 404 (NOT FOUND) How is that idempotent? -
Idempotence Refers to Resource State Even though the first DELETE
request returns a different status code than subsequent requests, the state of that resource (that is, it’s lack of existence) remains the same! -
PUT vs POST Redux PUT is idempotent POST is not
always idempotent, though it can be Use PUT to create or replace resources whose name you already know Use POST to create sub-resources and to append to a collection -
PUT vs POST Example PUT /talks/demystifying-‐the-‐rest-‐api ! {
talk_name: “Demystifying the REST API”, speaker: “Samantha Quiñones”, conferences: [] } -
PUT vs POST Example GET /talks/demystifying-‐the-‐rest-‐api ! 200 OK
{ talk_name: “Demystifying the REST API”, speaker: “Samantha Quiñones”, conferences: [] } -
PUT vs POST Example GET /talks/demystifying-‐the-‐rest-‐api ! {
talk_name: “Demystifying the REST API”, speaker: “Samantha Quiñones”, conferences: [{conference_name: “Northeast PHP”} {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, {conference_name: “Northeast PHP”}, -
PATCH Asks the server to modify a resource Newest method
Not widely supported (yet) Must be used with caution because of potentially high collision risk -
Why PATCH? PUT requires us to send a complete copy
of the resource, which causes a lot of overhead POST is often used to modify resources, but there is no standard methodology Standards (like JSON Patch) are being developed Patching XML is (partially) supported in RFC 5261 -
JSON Patch PATCH /foo ! 200 OK [
{ "op": "test", "path": "/a/b/c", "value": "foo" }, { "op": "remove", "path": "/a/b/c" }, { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }, { "op": "replace", "path": "/a/b/c", "value": 42 }, { "op": "move", "from": "/a/b/c", "path": "/a/b/d" }, { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" } ] -
CONNECT Used with proxies that allow for tunneling or protocol
switching and other things that are both interesting and intensely boring -
Status Codes 1xx - Informational Messages 2xx - Success 3xx
- Redirection 4xx - Client error (“you messed up!”) 5xx - Server error (“I messed up!”) -
What happens when you assume… REST makes assumptions safe by
applying well- established patterns A REST API should be self-documenting so that clients can easily integrate with it -
Use response codes everyone understands It’s easier for a client
to respond to “401 Unauthorized” than “500 Your login has timed out” -
Don’t overload POST “When in doubt, use POST” Reconsider your
application design. Does another method fit better? Are you not really working just with objects and interactions? Is REST the right pattern for your application? -
Resources RFC 2616 “Hypertext Transfer Protocol” (http://bit.ly/ LkW6OW) RFC 5789
“PATCH Method for HTTP” (http://bit.ly/1cFpvtq) JSON HAL Proposal (http://bit.ly/1kJLvgw) RFC 6902 “JSON PATCH” (http://bit.ly/LkWyww) Fielding’s Dissertation (http://bit.ly/1eTY8AI) REST Cookbook (http://restcookbook.com) -
PHP Resources HATEOAS for PHP: http://hateoas-php.org/ Well-supported, Symfony-ready HATEOAS library
REST APIs with Symfony2: The Right Way (http:// williamdurand.fr/2012/08/02/rest-apis-with- symfony2-the-right-way/) Building APIs You Won’t Hate - Phil Sturgeon https://leanpub.com/build-apis-you-wont-hate