URL yapınızı az çok özgürce değiştirme yeteneğinin yanı sıra HATEOAS, keşfedilebilirlik ve ayrıştırma için ne sunuyor?

Son zamanlarda, bir web API'sini "gerçekten RESTful" kıldığı iddia edilen kısıtlama olan Hypermedia'yı Uygulama Durumu Motoru (HATEOAS) olarak okudum. Temel olarak, mevcut durumdan yapabileceğiniz olası geçişlere verilen her yanıtı içeren bağlantılar dahil olmak üzere kaynar.

HATEOAS'ın anlayışıma dayalı olduğunu göstermeme izin verin - ve eğer bir şeyi kaçırırsam lütfen beni düzeltin.

/
    GET: {
        "_links": {
            "child": [
                { "href": "http://myapi.com/articles", "title": "articles" }
            ]
        }
    }

/articles?contains=HATEOAS
    GET: {
        "_items": [
            { "uri": "http://myapi.com/articles/0", "title": "Why Should I Care About HATEOAS?" },
            { "uri": "http://myapi.com/articles/1", "title": "HATEOAS: Problem or Solution?" }
        ],
        "_links": {
            "self": { "href": "http://myapi.com/articles", "title": "articles" },
            "parent": { "href": "http://myapi.com/", "title": "home" }
        }
    }

    POST: {
        "title": "A New Article",
        "body": "Article body",
        "tags": [ "tag1", "tag2" ]
    }

/articles/0
    GET: {
        "title": "Why Should I Care About HATEOAS?",
        "body": "Blah blah blah"
        "tags": [ "REST", "HATEOAS" ],
        "_links": {
            "self": { "href": "http://myapi.com/articles/0", "title": "article" },
            "parent": { "href": "http://myapi.com/articles", "title": "articles" }
        }
    }

HATEOAS'ın iki ana fayda sağladığı iddia ediliyor:

1. Kök URI'dan başlayarak tüm hizmet keşfedilebilir, belgelere artık gerek yok.

2. İstemci, şimdi URI yapısını özgürce değiştirebilen sunucudan ayrıştırılır. Bu, API sürümüne olan ihtiyacı ortadan kaldırır.

Ancak bana göre bir hizmet URI yapısından çok daha fazlası. Etkili kullanmak için ayrıca şunları da bilmeniz gerekir:

• hangi sorgu parametrelerini kullanabilirsiniz ve olası değerleri
• JSON / XML / POST / PATCH / etc isteklerinizde göndermeniz gereken dokümanların yapısı
• Sunucu tarafından gönderilen yanıtın yapısı
• oluşabilecek olası hatalar
• ...

Yukarıdakilere dayanarak, HATEOAS keşfedilebilirlik ve eşleştirme sorunlarının sadece küçük bir kısmını çözer. Yukarıdaki dört yönü belgelemeniz gerekir ve istemciler bunlar nedeniyle sunucuya güçlü bir şekilde bağlanmaya devam eder. İstemcileri kırmaktan kaçınmak için, API'nizi hala sürümlendirmeniz gerekir.

Sağladığı tek yarar, URL yapınızı az çok özgürce değiştirebilmenizdir (bu arada, "Soğuk URI'lar değişmez" ilkesine ne oldu ?). Anlayışım doğru mu?

Bence içgüdüleriniz büyük ölçüde doğru; Bu bildirilen faydalar gerçekten o kadar da büyük değildir, çünkü önemsiz olmayan herhangi bir web uygulaması için, müşterilerin sözdizimi kadar yaptıklarının anlamlarını da dikkate almaları gerekir.

Ancak bu, başvurunuzu HATEOAS ilkelerini takip etmemeniz gerektiği anlamına gelmez!

HATEOAS gerçekten ne anlama geliyor? Bunun anlamı başvurunuzu yapılanması prensip olarak böylece bir web sitesi gibi , ve yapmak isteyebileceğiniz tüm işlemler bazı karmaşık şema indirmek zorunda kalmadan keşfedilen edilebilir. (Sofistike WSDL şemaları her şeyi kapsayabilir, ancak yaptıkları zaman, hemen hemen her programcının anlama yeteneğini aştılar, yazabilsinler bile! HATEOAS'ı böyle bir karmaşıklığa karşı bir tepki olarak görebilirsin.)

HATEOAS sadece zengin bağlantılar anlamına gelmez. Neyin yanlış gittiğini tam olarak belirtmek için HTTP standardının hata mekanizmalarını kullanmak anlamına gelir ; “waaah!” ile cevap vermek zorunda değilsiniz. hayır ”ve bunun yerine neyin yanlış olduğunu ve müşterinin bu konuda neler yapabileceğini açıklayan bir belge sağlayabilir. Ayrıca, OPTIONS istekleri (müşterilerin hangi HTTP yöntemlerini kullanabileceklerini bulmalarına izin vermenin standart yolu) ve içerik türü anlaşması gibi şeyleri desteklemek , yanıtın biçiminin müşterilerin kullanabileceği bir biçime uyarlanabilmesi anlamına gelir. Açıklayıcı metin koymak anlamına gelir(veya daha büyük olasılıkla buna bağlar) böylece müşterilerin bilmedikleri durumlarda önemsiz durumlarda sistemi nasıl kullanacaklarını arayabilirler; açıklayıcı metin insan tarafından okunabilir veya makinede okunabilir olabilir (ve istediğiniz kadar karmaşık olabilir). Son olarak, istemcilerin bağları sentezlemediği anlamına gelir (sorgu parametreleri hariç); istemciler yalnızca bir bağlantı kullandıysanız bağlantı kullanır.

Sitenin bir kullanıcı tarafından (HTML yerine JSON veya XML okuyabilen, bu yüzden biraz garip) göz attığını düşünmelisiniz, bağlantılar için harika bir hafıza ve HTTP standartlarına ilişkin bir ansiklopedik bilgi, ancak başka bir deyişle yap.

Ve tabii ki, tarayıcı türünü kabul etmeye hazırsa, uygulamanızı kullanmasına izin verecek bir HTML (5) / JS istemcisi sunmak için içerik türü anlaşmasını kullanabilirsiniz. Sonuçta, RESTful API'niz herhangi bir iyiyse, bunun üzerine uygulamak için “önemsiz” mi olmalı?

Mesele şu ki, HATEOAS bir RESTful API'nin ne olduğunu tanımlayan ikinci bir direk ile gelmelidir: standartlaştırılmış ortam türü. Roy kendini fielding dedi

REST API, kaynakların temsilinde kullanılan medya türlerini tanımlamak için tanımlayıcı çabasının neredeyse tamamını harcamalıdır. "

Açıkça geçişi tanımlayan standartlaştırılmış bir medya türü ve kaynağı birbirine yönlendirmek için köprü metni ile, herhangi bir istemciyi bozmadan herhangi bir biçimde olabilen bir kaynak grafiği oluşturabilirsiniz. Web çalışması gibi, gerçekten: belge ile bağlantınız arasında bağlantı var ve belge, bu bağlantıların nasıl izleneceğini tanımlayan HTML ile yazılmıştır. <a href>GET, <form>GET veya POST (ve GET durumunda kullanılacak url şablonunu tanımla), <link type="text/css">GET ... vb. Tarayıcıların rasgele yapılandırılmış HTML sayfasında ve Web’de gezinmesini sağlar.

Tüm yaptığın nokta

• hangi sorgu parametrelerini kullanabilirsiniz ve olası değerleri
• JSON / XML / POST / PATCH / etc isteklerinizde göndermeniz gereken dokümanların yapısı
• Sunucu tarafından gönderilen yanıtın yapısı
• oluşabilecek olası hatalar

Standartlaştırılmış ortam türünün tanımına uyulması gereken noktalar . Tabii ki, bu daha zordur ve çoğu insanın bir "REST" API'si tanımlarken düşündüğü bir şey değildir. RESTful API’ya sahip olmak için yalnızca işletme varlıklarını alıp özniteliklerini bir JSON belgesine sokamazsınız.

Tabii ki, olan şey REST'in bir şekilde "karmaşık SOAPy olayı yerine HTTP kullan" anlamına gelmesidir. Sadece HTTP ve HyperText kullanmak, RESTful olmak için yeterli değil, çoğu insanın yanlış yaptığı şey bu.

Bunun kötü bir şey olması gerekmediğinden değil: REST, uzun vadede sürdürülebilirlik ve evrimlilik karşılığında performanstan ve geliştirme kolaylığından fedakarlık eder. Büyük girişimcilik uygulama entegrasyonu için yapıldı. Sabit kodlanmış JSON yapısına sahip küçük bir web API, ihtiyacınız olan şey olabilir. Sadece buna REST, geçici bir web API'sı deyin, başka bir şey yok. Ve bu berbat olduğu anlamına gelmez, sadece REST'in sınırını izlemeye çalışmadığı anlamına gelir.

daha fazla okuma

• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• http://martinfowler.com/articles/richardsonMaturityModel.html

Umarım bu yardım biraz netleşir :)

Ne tür isteklerin gönderileceği hakkında daha fazla bilgi içeren daha zengin yanıtlar vermeye çalışan bazı Hypermedia formatları vardır ve yanıtı daha fazla bilgi ile zenginleştirmekten alıkoyacak hiçbir şey yoktur.

İşte bir Siren belgesi örneği :

{
  "class": [ "order" ],
  "properties": { 
      "orderNumber": 42, 
      "itemCount": 3,
      "status": "pending"
  },
  "entities": [
    {
      "class": [ "info", "customer" ],
      "rel": [ "http://x.io/rels/customer" ], 
      "properties": { 
        "customerId": "pj123",
        "name": "Peter Joseph"
      },
      "links": [
        { "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
      ]
    }
  ],
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        { "name": "orderNumber", "type": "hidden", "value": "42" },
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ],
  "links": [
    { "rel": [ "self" ], "href": "http://api.x.io/orders/42" },
    { "rel": [ "previous" ], "href": "http://api.x.io/orders/41" },
    { "rel": [ "next" ], "href": "http://api.x.io/orders/43" }
  ]
}

Gördüğünüz gibi, nasıl arama ile ilgili bilgi actionsiletide sağlanır ve sonra bu bilgiler yorumlanarak müşteri değişime karşı daha dirençli hale gelir.

Bu, eğer relsabit bir sözcükten ziyade, aranabilen URI'lar ise, özellikle güçlü hale gelir .

HATEAOS hizmetleri için "belgelere artık gerek yok" u nereden okudunuz? Söylediğiniz gibi, hala bağlantıların anlamını belgelemeniz gerekiyor. Bununla birlikte, HATEOAS ile URI'lerin çoğunun yapısını belgelemenize ve dolayısıyla sonsuza kadar kalmanıza gerek kalmaz.

HATEOAS bir servis uygulayıcısının müşterinin dayandığı küçük bir URI setini değiştirmeden uygulamayı önemli ve verimli bir şekilde değiştirmesine ve ölçeklendirmesine izin verir. Az sayıdaki giriş noktasını büyük bir setten farklı tutmak kolaydır. Bu nedenle, hizmete genel giriş noktalarının sayısının azaltılması ve dinamik olarak alt kaynaklara bağlantılar sağlanması (HATEOAS), HATEOAS dışı hizmetlerden daha iyi bir şekilde "Cool URI'lar değişmez" i desteklemektedir.

(HATEOAS), bir web API'sini "gerçekten RESTful" yaptığını iddia eden kısıtlama

Gerçek bir REST API'sı yapan tek şey, sadece tek bir değil, tüm kısıtlamalara uymaktır.

Ancak bana göre bir hizmet URI yapısından çok daha fazlası. Etkili kullanmak için, şunu da bilmeniz gerekir: ...

Bu yüzden diğer kısıtlamalara, açıklayıcı mesaja, vb. İhtiyacımız var.

İstemcileri kırmaktan kaçınmak için, API'nizi hala sürümlendirmeniz gerekir.

Nasıl denerseniz çalışın, API'nızı sürümlendirmeniz gerekir. Bir REST istemcisinde, mesajı açıklayan RDF kelime bilgisine dayanarak, hangi bağlantıları izleyeceğiniz ve hangi özellikleri toplamanız gerektiğine ilişkin bir şeyler yapmak istediğiniz bir sayfaya nasıl gideceğinizi bilmeniz gerekir. Bu kelimeden bir şeyi değiştirmeniz veya çıkarmanız gerekirse, muhtemelen tüm müşterilerinizi kıracak ve yeni bir versiyona ihtiyacınız olacak. Bu nedenle REST'in erken yayınlamanız gereken bir şey olmadığını düşünüyorum (ve sürekli API'yi değiştirirken modeli anlayın), aksi halde birçok versiyonunuz olur. İlk önce yapabileceğiniz sağlam bir etki alanı modeline ihtiyacınız var ...