JAX RS – 33 – HATEOAS & Richardson Model – 01

Merhaba Arkadaslar
Bu bolumde HATEOAS kavramini ve  Richardson Model ‘i inceleyecegiz.

Internette/Web’te , HTML linkleri browser/tarayicinin durumunu degistirmemize izin verir.
Bir web sayfasi okurken , cogu zaman sayfada bir cok link daha olacaktir ve bunlarin her biri bir dokuman/durum(state) temsil etmektedir. Linke tikladigimizda browser’in durumu/state degisecek ve diger web sayfasi acilacaktir. Boylece bir Web sitesine giris yaptigimizda sonrasinda bu sayfa uzerinde diger bilgilere/sayfalara ulasmamiz cok daha kolay olacaktir.

Iste HATEOAS kavrami da bu mantiktan yola cikmaktadir.
HATEOAS kavrami ; RESTful web service’in extra olarak bilgi sunmasi ve boylece tek bir giris noktasindan sonra uygulamada yapabilecegimiz isleri kolayca gormemiz ve yapmamiza olanak saglar.

The idea of HATEOAS is that your data format provides extra information 
on how to change the state of your application. 
Hypermedia helps make clients more flexible by avoiding hard-coding REST URLs. 
It can also help in self-documenting REST APIs.
https://blogs.oracle.com/theaquarium/hypermediahateoas-support-in-jax-rs-2java-ee-7
The point of hypermedia controls is that they tell us what we can do next, 
and the URI of the resource we need to manipulate to do it.

HATEOAS , Hypermedia As The Engine Of Application State olarak ifade edilmektedir. Bir RESTFul uygulama mimarisi kisitlamasidir (constraint)

HATEOAS (Hypermedia as the Engine of Application State) 
is a constraint of the REST application architecture.

Peki Web Service ile HATEOAS kavrami nasil iliskilendirilmektedir ?
XML ya da JSON formatindaki response data’sina gomulu link (hypermedia) ekleme ile HATEOAS kavramini Web Service ile iliskilendirebiliriz.

When you’re applying HATEOAS to web services, 
the idea is to embed links within your XML or JSON documents.

XML tabanli RESTFul Web Service uygulamalari , HATEOAS icin Atom Syndication(sendika) Format i kullanmaktadir.

Atom , birbiriyle iliskili “feed” adi verilen bilgilerden olusan XML tabanli bir dokuman formatidir.

Atom is an XML-based document format that describes lists of related information known 
as "feeds." Feeds are composed of a number of items, known as "entries," 
each with an extensible set of attached metadata.

https://www.ibm.com/developerworks/library/x-atom10/index.html

<feed xmlns="http://www.w3.org/2005/Atom"
      xml:base="http://www.example.org/">
  <id>http://www.example.org/pictures</id>
  <title>My Picture Gallery</title>
  <updated>2005-07-15T12:00:00Z</updated>
  <author>
    <name>James M Snell</name>
  </author>
  <entry>
     <id>http://www.example.org/entries/1</id>
     <title>Trip to San Francisco</title>
     <link href="/entries/1" />
     <updated>2005-07-15T12:00:00Z</updated>
     <summary>A picture of my hotel room in San Francisco</summary>
     <content type="image/png" src="/mypng1.png" />
  </entry>
  <entry>
    <id>http://www.example.org/entries/2</id>
    <title>My new car</title>
    <link href="/entries/2" />
    <updated>2005-07-15T12:00:00Z</updated>
    <summary>A picture of my new car</summary>
    <content type="image/png" src="/mypng2.png" />
  </entry>
</feed>

PayPal in Developer sitesini inceleyelim ;
https://developer.paypal.com/docs/api/reference/api-responses/#hateoas-links

{  
  "links": [{
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832",
    "rel": "self",
    "method": "GET"
  }, {
    "href": "https://api.paypal.com/v1/payments/sale/36C38912MN9658832/refund",
    "rel": "refund",
    "method": "POST"
  }, {
    "href": "https://api.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI",
    "rel": "parent_payment",
    "method": "GET"
  }]
}

Burada ornek bir response/cevap bilgisi yer almaktadir.
Id numaralari dummy degerler olup , bir payment islemini temsil etmektedir.

GET istegi ile ilgili URI icin istek yaptigimizda ilgili payment’a dair bilgileri elde edebiliriz.

GET https://api.paypal.com/v1/payments/sale/36C38912MN9658832

Eger iade/refund islemi yapmak istiyorsak bu durumda HTTP POST ile ilgili URI adresine istek gondermemiz gerekmektedir.

POST https://api.paypal.com/v1/payments/sale/36C38912MN9658832/refund

Ya da onceki ana odemeye/parent payment i gormek istiyorsak

GET https://api.paypal.com/v1/payments/payment/PAY-5YK922393D847794YKER7MUI

Richardson Model

Richardson Modelinde 3 tane faktor RESTFul service in olgunluk/gelismislik seviyesini gostermektedir.

  • URI (Uniform Resource Identifier)
  • HTTP Methods
  • Hypermedia

Richadson olgunluk/gelismislik seviyesini 4’e ayirmaktadir.

  • Level Zero
  • Level One
  • Level Two
  • Level Three

Level Zero : The Swamp of POX

Level Zero seviyesinde servisin sadece tek bir giris noktasi olmaktadir (URI) ve tek bir HTTP method kullanilmaktadir (tipik olarak HTTP POST)

XML-RPC (Remote Procedure Call, SOAP/JAX-WS web serviceleri bunun tipik bir ornegidir. JAX-WS web service’lerinde tek bir URI/endpoint olmaktadir ve SOAP payload’lari HTTP POST ile gonderilmektedir.

Bu level in tipik ozelligi ; single URI single verb/ one URI one HTTP method

Level One : Resources

Bu seviyede 3 faktorden (URI , HTTP Methods , HATEOAS) sadece bir tanesi ; URI (Uniform Resource Identifier) kullanilmaktadir.
Level One’da bir den fazla/multiple URI adresi hizmet vermektedir fakat yine tek tip HTTP Method kullanilmaktadir. (Genel olarak HTTP POST)

Bu level in tipik ozelligi; multiple URI based resources , single verb

Level Two : Http Verbs

Bu seviyede 3 faktorden URI ve HTTP Methodlari kullanilmaktadir.

Ornegin CRUD ( Create , Read , Update , Delete) servisleri icin farkli URI adresi olmakta ve her birine karsilik bir HTTP Method kullanilmaktadir. (POST , GET , PUT , Delete)

Bu level in tipik ozelligi; multiple URI based resources , multiple verb

Level Three : Hypermedia Controls

Bu level in tipik ozelligi; HATEOAS
Bu seviyede 3 faktorden 3’u de kullanilmaktadir.

The point of hypermedia controls is that they tell us what we can do next, 
and the URI of the resource we need to manipulate to do it.
Martin Fowler
https://martinfowler.com/articles/richardsonMaturityModel.html

Github kaynak kodlar / source folder
injavawetrust.resteasy
injavawetrust.jersey

Yazimi burada sonlandiriyorum.
Herkese Bol Javali Gunler dilerim.

Print Friendly, PDF & Email

Leave a Reply

Your email address will not be published. Required fields are marked *