Dizajn REST API-ja

4. lipnja 2013.
Dizajn REST API-ja
Denis Kranjčec, Srce
denis.kranjcec@srce.hr

4. lipnja 2013.
Dizajn REST API-ja
• Što je REST i kada ga koristiti?
• Dizajn URL-ova resursa
• HTTP metode i CRUD operacije
• Verzioniranje API-ja
• Obrada pogrešaka
• Sigurnost
• HATEOAS

4. lipnja 2013.
Što je REST? (1)
• „Representational State Transfer (REST) is a style of
software architecture for distributed systems such as
the World Wide Web.”
https://en.wikipedia.org/wiki/Representational_state_transfer
• „The term representational state transfer was
introduced and defined in 2000 by Roy Fielding in his
doctoral dissertation.”
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

4. lipnja 2013.
Što je REST? (2)
• Constraints
– Client–server
– Stateless
– Cacheable
– Layered system
– Uniform interface
• „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.”
– Code on demand (optional)

4. lipnja 2013.
Richardson Maturity Model
• Level 0
– One URI
– SOAP, XML RPC, POX

4. lipnja 2013.
• Level 0
– One URI
• Level 1
– Many URIs
– One HTTP method

4. lipnja 2013.
• Level 0
– One URI
• Level 1
– Many URIs
– One HTTP method
• Level 2
– Many URIs
– Multiple HTTP methods

4. lipnja 2013.
• Level 0
– One URI
• Level 1
– Many URIs
– One HTTP method
• Level 2
– Many URIs
– Multiple HTTP methods
• Level 3
– Level2 + Hypermedia (Resources decribe their own capabilities and
interconnections)

4. lipnja 2013.
Što je REST? (3)
• „REST is software design on the scale of decades:
every detail is intended to promote software longevity
and independent evolution. Many of the constraints
are directly opposed to short-term efficiency.
Unfortunately, people are fairly good at short-term design, and
usually awful at long-term design.” - Roy Fielding
• „A truly RESTful API looks like hypertext.” – Roy
Fielding

4. lipnja 2013.
Dizajn reprezentacije resursa
• „A resource is not the thing that is transferred across
the wire... [that] is only a representation.” – Roy
Fielding
• Dizajn reprezentacije resursa:
– Zahtjeva ekspertno znanje o domeni
– Nezavisan je od implementacije
– Korisno ga je prilagoditi use case-u

4. lipnja 2013.
Dizajn URL-a (1)
• http://www.srce.hr/dohvatistudente?godina=2
– OK za dohvat (GET)
– OK za dodavanje, izmjenu i/ili brisanje? (POST, PUT,
DELETE)

4. lipnja 2013.
Dizajn URL-a (1)
• http://www.srce.hr/dohvatistudente?godina=2
– OK za dohvat (GET)
– OK za dodavanje, izmjenu i/ili brisanje? (POST, PUT,
DELETE)
• http://www.srce.hr/student/godina/2
– OK?

4. lipnja 2013.
Dizajn URL-a (2)
• http://www.srce.hr/student/oib/1234567890
• http://www.srce.hr/student/jmbg/04061332112
• Jedan URL identificira točno jedan resurs, ali jedan
resurs može imati više URL-ova.
• Korisno je da je URL pamtljiv i predvidljiv, iako to nije
nužno.

4. lipnja 2013.
Dizajn URL-a (3)
• http://www.srce.hr/visokouciliste/student
• http://www.srce.hr/visokouciliste/studij/student
• http://www.srce.hr/visokouciliste/studij/godina/2/s
tudent
• Korisno je da je jasna hijerarhija resursa iz URL-a
• URL mora definirati server, a ne klijent (hypermedia).
Inače smo izložili previše detalja implementacije
klijentu i naknadne promjene URL-a više nisu
moguće/lako izvedive.

4. lipnja 2013.
HTTP metode i CRUD operacije (1)
• Create = PUT ?
• Retrieve = GET ?
• Update = POST ?
• Delete = DELETE ?
• http://www.w3.org/Protocols/rfc2616/rfc2616-
sec9.html
Hypertext Transfer Protocol -- HTTP/1.1
RFC 2616 Fielding, et al.
Method Definitions

4. lipnja 2013.
HTTP metode i CRUD operacije (2)
• Create = PUT if and only if you are sending the full content of
the specified resource (URL).
• Create = POST if you are sending a command to the server to
create a subordinate of the specified resource, using some
server-side algorithm.
• Retrieve = GET.
• Update = PUT if and only if you are updating the full content of
the specified resource.
• Update = POST if you are requesting the server to update one
or more subordinates of the specified resource.
• Delete = DELETE.

4. lipnja 2013.
Verzioniranje API-ja (1)
• http://www.srce.hr/api/v1/student

4. lipnja 2013.
• „Content negotiation is a mechanism defined in the
HTTP specification that makes it possible to serve
different resource representation at the same
URI...”
https://en.wikipedia.org/wiki/Content_negotiation

4. lipnja 2013.
• „Content negotiation is a mechanism defined in the
HTTP specification that makes it possible to serve
different resource representation at the same
URI...”
https://en.wikipedia.org/wiki/Content_negotiation
• http://www.primjer.hr/student
• Accept: application/vnd.student-v1+xml
• Accept: application/vnd.student-v2+xml
• Accept: application/vnd.student+json
• Accept-Language, Accept-Encoding
http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html (Header Field Definitions)

4. lipnja 2013.
Obrada pogrešaka (1)
• Obavezno koristiti ispravne HTTP status codes
http://restpatterns.org/HTTP_Status_Codes
– 1xx - Informational
– 2xx - Successful
– 3xx - Redirection
– 4xx - Client Error
– 5xx - Server Error

4. lipnja 2013.
Obrada pogrešaka (2)
http://stackoverflow.com/questions/2342579/http-status-code-for-update-and-delete

4. lipnja 2013.
Sigurnost
• HTTP Secure – https://...
• Basic access authentication
– HTTP Header
Authorization Basic amF2YWNybzpkZW5pcw==
• OAuth 2.0
• Digest access authentication

4. lipnja 2013.
Primjer – zahtjev/odgovor
• HTTP Header zahtjeva:
– GET www.primjer.hr/student HTTP/1.1
– Accept
text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
– Accept-Language en-us,en;q=0.5
– Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7
– Authorization Basic amF2YWNybzpkZW5pcw==
• HTTP Header odgovora:
– HTTP/1.1 200 OK
– Content-Type application/xml;charset=UTF-8
– Date Tues, 4 Jun 2013 17:39:07 GMT

4. lipnja 2013.
HATEOAS (1)
• HATEOAS (Hypermedia as the Engine of Application
State)
– The principle is that a client interacts with a network
application entirely through hypermedia provided
dynamically by application servers. A REST client needs no
prior knowledge about how to interact with any particular
application or server beyond a generic understanding of
hypermedia.
• Hypermedia is used as a logical extension of the term hypertext in
which graphics, audio, video, plain text and hyperlinks intertwine to
create a generally non-linear medium of information.
• Hyperlink is a reference to data that the reader can directly follow, or
that is followed automatically.

4. lipnja 2013.
HATEOAS (2)
• A REST client enters a REST application through a simple
fixed URL.
• All future actions the client may take are discovered within
resource representations returned from the server.
• The media types used for these representations, and the link
relations they may contain, are standardized.
• The client transitions through application states by selecting
from the links within a representation or by manipulating the
representation in other ways afforded by its media type. In this
way, RESTful interaction is driven by hypermedia, rather than
out-of-band information.
http://en.wikipedia.org/wiki/HATEOAS

4. lipnja 2013.
HATEOAS (3)
• „Hypermedia Types are MIME media types that
contain native hyper-linking semantics that induce
application flow. For example, HTML is a hypermedia
type; XML is not.” - Mike Amundsen

4. lipnja 2013.
HATEOAS (3)
• „Hypermedia Types are MIME media types that
contain native hyper-linking semantics that induce
application flow. For example, HTML is a hypermedia
type; XML is not.” - Mike Amundsen
• Koji hypermedia type koristiti?
– Nema (jednog) standarda za REST API-je
– HAL (Hypertext Application Language)
– Collection+JSON
– ...

4. lipnja 2013.
HAL (1)
• HAL (Hypertext
Application Language) - A
lean hypermedia type
http://stateless.co/hal_specification.html
– HAL is a format you can use
in your API that gives you a
simple way of linking. It has
two variants, one in JSON
(application/hal+json) and
one in XML
(application/hal+xml).
• Primjer – HAL Talk
http://haltalk.herokuapp.com/explorer/browser.html#/

4. lipnja 2013.
HAL (2)
<resource href="/orders">
<link rel="next" href="/orders?page=2" />
<link rel="find" href="/orders{?id}" templated="true" />
<link rel="admin" href="/admins/2" title="Fred" />
<link rel="admin" href="/admins/5" title="Kate" />
<currentlyProcessing>14</currentlyProcessing>
<shippedToday>20</shippedToday>
<resource rel="order" href="/orders/123">
<link rel="customer" href="/customers/7809" />
<link rel="basket" href="/baskets/98712„ />
<total>30.00</total>
<currency>USD</currency>
<status>shipped</status>
</resource>
...
</resource>
</resource>

4. lipnja 2013.
HAL (2)
</resource>
...
</resource>
</resource>
Link Relations (IANA)
http://www.iana.org/assignments/link-
relations/link-relations.xml

4. lipnja 2013.
HAL (2)
</resource>
...
</resource>
</resource>
URI Template (RFC6570)
http://tools.ietf.org/html/rfc6570

4. lipnja 2013.
REST
• REST in Practice
– Jim Webber, Savas Parastatidis, Ian Robinson
• rest-discuss · The REST Architectural Style
List
– http://tech.groups.yahoo.com/group/rest-
discuss/
• Roy T. Fielding (@fielding)
– http://roy.gbiv.com/untangled/
• Mike Amundsen (@mamund)
– http://amundsen.com/
• ...

Dizajn REST API-ja

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (9)

Similaire à Dizajn REST API-ja

Similaire à Dizajn REST API-ja (20)

Plus de Denis Kranjčec

Plus de Denis Kranjčec (6)

Dernier

Dernier (20)

Dizajn REST API-ja