dizajn rest api-ja - javacro conference · dizajn rest api-ja • Što je rest i kada ga koristiti?...

Dizajn REST API-ja

4. lipnja 2013.

Denis Kranjčec, [email protected]

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.



• Level 1– Many URIs

4. lipnja 2013.

– Many URIs– One HTTP method




4. lipnja 2013.


• Level 2– Many URIs– Multiple HTTP methods




4. lipnja 2013.


• 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


4. lipnja 2013.




• „Content negotiation is a mechanism defined in the

4. lipnja 2013.


HTTP specification that makes it possible to serve

different resource representation at the same

URI...”https://en.wikipedia.org/wiki/Content_negotiation



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.


HATEOAS (3)

• „Hypermedia Types are MIME media types that

contain native hyper-linking semantics that induce

application flow. For example, HTML is a hypermedia


4. lipnja 2013.


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


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

HAL (2)








Link Relations (IANA)

http://www.iana.org/assignments/link-

relations/link-relations.xml

4. lipnja 2013.








</resource>


...

</resource>

</resource>

HAL (2)








URI Template (RFC6570)

http://tools.ietf.org/html/rfc6570

4. lipnja 2013.








</resource>


...

</resource>

</resource>

HAL (2)








4. lipnja 2013.








</resource>


...

</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/

• ...

Dizajn REST API-ja

4. lipnja 2013.

Denis Kranjčec, [email protected]

dizajn rest api-ja - javacro conference · dizajn rest api-ja • Što je rest i kada ga koristiti?...

Documents