Upload
vocong
View
217
Download
0
Embed Size (px)
Citation preview
Dizajn REST API-ja
• Što je REST i kada ga koristiti?• Dizajn URL-ova resursa• HTTP metode i CRUD operacije• Verzioniranje API-ja
4. lipnja 2013.
• Verzioniranje API-ja• Obrada pogrešaka• Sigurnost• HATEOAS
Š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
•
4. lipnja 2013.
• „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.htmhttp://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
Što je REST? (2)
• Constraints– Client–server– Stateless– Cacheable
4. lipnja 2013.
– 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)
Richardson Maturity Model
• Level 0– One URI– SOAP, XML RPC, POX
4. lipnja 2013.
Richardson Maturity Model
• Level 0– One URI– SOAP, XML RPC, POX
• Level 1– Many URIs
4. lipnja 2013.
– Many URIs– One HTTP method
Richardson Maturity Model
• Level 0– One URI– SOAP, XML RPC, POX
• Level 1– Many URIs
4. lipnja 2013.
– Many URIs– One HTTP method
• Level 2– Many URIs– Multiple HTTP methods
Richardson Maturity Model
• Level 0– One URI– SOAP, XML RPC, POX
• Level 1– Many URIs
4. lipnja 2013.
– Many URIs– One HTTP method
• Level 2– Many URIs– Multiple HTTP methods
• Level 3– Level2 + Hypermedia (Resources decribe their own capabilities and
interconnections)
Š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.
4. lipnja 2013.
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
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:
4. lipnja 2013.
• Dizajn reprezentacije resursa:– Zahtjeva ekspertno znanje o domeni– Nezavisan je od implementacije– Korisno ga je prilagoditi use case-u
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)
•
4. lipnja 2013.
• http://www.srce.hr/student/godina/2
– OK?
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
4. lipnja 2013.
• 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.
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
4. lipnja 2013.
• 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.
HTTP metode i CRUD operacije (1)
• Create = PUT ?• Retrieve = GET ?• Update = POST ?• Delete = DELETE ?
4. lipnja 2013.
• Delete = DELETE ?
• http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.htmlHypertext Transfer Protocol -- HTTP/1.1RFC 2616 Fielding, et al.
Method Definitions
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.
4. lipnja 2013.
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.
Verzioniranje API-ja (1)
• http://www.srce.hr/api/v1/student
• http://www.srce.hr/api/v2/student
4. lipnja 2013.
Verzioniranje API-ja (1)
• http://www.srce.hr/api/v1/student
• http://www.srce.hr/api/v2/student
• „Content negotiation is a mechanism defined in the
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
Verzioniranje API-ja (2)
• „Content negotiation is a mechanism defined in the
HTTP specification that makes it possible to serve
different resource representation at the same
URI...”
4. lipnja 2013.
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-Encodinghttp://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html (Header Field Definitions)
Obrada pogrešaka (1)
• Obavezno koristiti ispravne HTTP status codeshttp://restpatterns.org/HTTP_Status_Codes
– 1xx - Informational
– 2xx - Successful
– 3xx - Redirection
4. lipnja 2013.
– 3xx - Redirection
– 4xx - Client Error
– 5xx - Server Error
Obrada pogrešaka (2)
4. lipnja 2013.
http://stackoverflow.com/questions/2342579/http-status-code-for-update-and-delete
Sigurnost
• HTTP Secure – https://...
• Basic access authentication– HTTP Header
4. lipnja 2013.
– HTTP HeaderAuthorization Basic amF2YWNybzpkZW5pcw==
• OAuth 2.0• Digest access authentication
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
4. lipnja 2013.
– 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
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
4. lipnja 2013.
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.
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
4. lipnja 2013.
• 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
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.
type; XML is not.” - Mike Amundsen
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.
type; XML is not.” - Mike Amundsen
• Koji hypermedia type koristiti?– Nema (jednog) standarda za REST API-je– HAL (Hypertext Application Language)– Collection+JSON– ...
HAL (1)
• HAL (HypertextApplication Language) - A
lean hypermedia typehttp://stateless.co/hal_specification.html
– HAL is a format you can use
4. lipnja 2013.
– 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 Talkhttp://haltalk.herokuapp.com/explorer/browser.html#/
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>
4. lipnja 2013.
<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 rel="order" href="/orders/124">
...
</resource>
</resource>
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>
4. lipnja 2013.
<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 rel="order" href="/orders/124">
...
</resource>
</resource>
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>
Link Relations (IANA)
http://www.iana.org/assignments/link-
relations/link-relations.xml
4. lipnja 2013.
<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 rel="order" href="/orders/124">
...
</resource>
</resource>
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>
URI Template (RFC6570)
http://tools.ietf.org/html/rfc6570
4. lipnja 2013.
<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 rel="order" href="/orders/124">
...
</resource>
</resource>
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>
4. lipnja 2013.
<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 rel="order" href="/orders/124">
...
</resource>
</resource>
REST
• REST in Practice– Jim Webber, Savas Parastatidis, Ian Robinson
• rest-discuss · The REST Architectural Style List– http://tech.groups.yahoo.com/group/rest-
4. lipnja 2013.
– http://tech.groups.yahoo.com/group/rest-discuss/
• Roy T. Fielding (@fielding)– http://roy.gbiv.com/untangled/
• Mike Amundsen (@mamund)– http://amundsen.com/
• ...