REST hakkında bildiğimi sandığım şeylerin büyük bir kısmı görünüşe göre yanlış - ve yalnız değilim. Bu soru uzun bir girişe sahip, ancak bilgi biraz dağınık olduğu için gerekli görünüyor. Bu konuya zaten aşina iseniz asıl soru sonunda gelir.
Roy Fielding'in REST API'lerinin hiper metne dayalı olması gerektiğinin ilk paragrafından itibaren, çalışmasının büyük ölçüde yanlış yorumlandığına inandığı oldukça açık:
Herhangi bir HTTP tabanlı arayüzü REST API olarak adlandıran insan sayısı beni hayal kırıklığına uğratıyor. Bugünün örneği SocialSite REST API'sidir . Bu RPC'dir. RPC diye haykırıyor. Ekranda o kadar çok bağlantı var ki ona bir X derecesi verilmesi gerekiyor.
Fielding, bir REST API'nin birkaç özelliğini listelemeye devam ediyor. Bazıları, SO ve diğer forumlarda hem genel uygulamaya hem de genel tavsiyelere aykırı görünüyor. Örneğin:
Bir REST API, ilk URI (yer imi) ve hedeflenen kitle için uygun olan (yani API'yi kullanabilecek herhangi bir istemci tarafından anlaşılması beklenen) standartlaştırılmış ortam türleri kümesinin ötesinde hiçbir ön bilgi olmadan girilmelidir. ...
Bir REST API, sabit kaynak adlarını veya hiyerarşileri tanımlamamalıdır (istemci ve sunucunun açık bir bağlantısı). ...
Bir REST API, tanımlayıcı çabasının neredeyse tamamını kaynakları temsil etmek ve uygulama durumunu yönlendirmek için kullanılan ortam türlerini tanımlamaya veya mevcut standart ortam türleri için genişletilmiş ilişki adlarını ve / veya hiper metin etkin biçimlendirmeyi tanımlamaya harcamalıdır. ...
"Köprü metni" fikri, URI yapısından veya HTTP fiillerinin ne anlama geldiğinden çok daha fazla merkezi bir rol oynar. "Köprü metni" yorumlardan birinde tanımlanmıştır:
Ben [Fielding] hiper metin dediğimde, bilginin ve kontrollerin eşzamanlı sunumunu kastediyorum, öyle ki bilginin kullanıcının (veya otomatın) seçimler elde etmesi ve eylemleri seçmesi için bir yeterlilik haline gelmesi. Hypermedia, bir medya akışına geçici bağlantıların dahil edilmesinin metnin ne anlama geldiğine ilişkin bir genişletmedir; çoğu araştırmacı bu farkı bıraktı.
Köprü metninin bir tarayıcıda HTML olması gerekmez. Makineler, veri biçimini ve ilişki türlerini anladıklarında bağlantıları izleyebilir.
Bu noktada tahmin ediyorum, ancak yukarıdaki ilk iki nokta, aşağıdakine benzeyen bir Foo kaynağı için API belgelerinin, istemci ve sunucu arasında sıkı bir bağlantıya yol açtığını ve bir RESTful sistemde yeri olmadığını gösteriyor.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Bunun yerine, bir temsilci, örneğin / foos'a karşı bir GET isteği göndererek tüm Foo'lar için URI'leri keşfetmeye zorlanmalıdır. (Bu URI'lerin yukarıdaki modeli izlediği ortaya çıkabilir, ancak bu noktanın dışındadır.) Yanıt, her bir öğeye nasıl erişileceğini ve bununla neler yapılabileceğini iletebilen bir ortam türü kullanır ve yukarıdaki üçüncü noktaya yol açar . Bu nedenle, API dokümantasyonu, yanıtta bulunan hipermetin nasıl yorumlanacağını açıklamaya odaklanmalıdır.
Ayrıca, bir Foo kaynağına bir URI talep edildiğinde, yanıt, bir aracının, örneğin URI'leri aracılığıyla ilişkili ve ana kaynaklara erişerek veya oluşturulduktan sonra harekete geçerek nasıl ilerleyeceğini keşfetmesi için gereken tüm bilgileri içerir / bir kaynağın silinmesi.
Tüm sistemin anahtarı, yanıtın, kendisi devam etmek için aracıya seçenekleri ileten bir medya türünde bulunan hiper metinden oluşmasıdır. Bir tarayıcının insanlar için çalışma şeklinden farklı değildir.
Ama bu, şu andaki en iyi tahminim.
Fielding , tartışmasının çok soyut, örneklerden yoksun ve jargon açısından zengin olduğu yönündeki eleştirilere yanıt verdiği bir takip yayınladı :
Diğerleri, yazdıklarımı bugünün bazı pratik endişelerine daha doğrudan veya uygulanabilir yollarla deşifre etmeye çalışacaklar. Muhtemelen yapmayacağım, çünkü bir sonraki konuyla boğuşmakla, bir konferansa hazırlanmakla, başka bir standart yazmakla, uzak bir yere seyahat etmekle ya da maaş çekimi kazandığımı hissetmeme izin veren küçük şeyler yapmakla çok meşgulüm.
Öyleyse, pratik bir zihniyete sahip olan REST uzmanları için iki basit soru: Fielding'in söylediklerini nasıl yorumluyorsunuz ve REST API'lerini belgelerken / uygularken bunu nasıl uygulamaya koyuyorsunuz?
Düzenleme: Bu soru, bahsettiğiniz şey için bir adınız yoksa bir şeyi öğrenmenin ne kadar zor olabileceğinin bir örneğidir. Bu durumda adı "Uygulama Durumu Motoru Olarak Hiper Ortam" (HATEOAS) adıdır.