10 yıldan fazla bir süre sonra OP'de talep edilen bir şeyin bir REST mimarisinde nasıl tasarlanabileceğini gerçekten belirten bir cevap olmadığını görmek biraz üzülüyorum, bu yüzden şimdi bunu yapmam gerektiğini hissediyorum.
İlk önce, REST nedir ?! REST veya ReST kısaltması, "Temsili Durum Transferi" anlamına gelir ve bir kaynağın durumunun belirli bir gösterim biçiminde değişimini tanımlar. Temsil biçimi, müzakere edilen medya türüne bağlıdır. Durumunda application/htmltemsil biçimi HTML akışı muhtemelen belli noktalarda belli unsurları konumlandırmak için biçimlendirme bazı stil uygulandıktan sonra, tarayıcıda oluşturulduğu metin içeriği biçimlendirilmiş olabilir.
REST prensip olarak hepimizin bildiği göz atılabilir Web'in genelleştirilmesidir, ancak sadece tarayıcıları değil her türlü uygulamayı hedefler. Bu nedenle, tasarım gereği Web için geçerli olan aynı kavramlar bir REST mimarisi için de geçerlidir. "RESTful" yolunda bir şeyin nasıl elde edileceği gibi bir soru, bir Web sayfasında bir şeyin nasıl elde edileceği sorusunun yanıtlanması ve ardından aynı kavramların uygulama katmanına uygulanması etrafında çözülür.
Web tabanlı bir hesap makinesi genellikle girilen verileri sunucuya göndermeden önce hesaplamak için bazı değerler girmenizi sağlayan bir "sayfa" ile başlayabilir. HTML'de bu genellikle <form>bir istemciye ayarlanabilecek parametreler, isteği gönderilecek hedef konum ve giriş verilerinin gönderilmesinden sonra uygulanacak temsil formatı hakkında öğreten HTML öğeleri aracılığıyla gerçekleştirilir . Bu, örneğin şöyle görünebilir:
<html>
<head>
...
</head>
<body>
<form action="/../someResource" method="post" enctype="application/x-www-form-urlencoded">
<label for="firstNumber">First number:</label>
<input type="number" id="firstNumber" name="firstNumber"/>
<label for="secondNumber">Second number:</label>
<input type="number" id="secondNumber" name="secondNumber"/>
<input type="submit" value="Add numbers"/>
</form>
</body>
</html>
Yukarıdaki örnek, kullanıcı veya başka bir otomata tarafından doldurulabilen iki giriş alanının olduğunu ve gönderme giriş elemanını çağırdıktan sonra tarayıcının, giriş verilerini application/x-www-form-urlencodedgönderilen bir temsil formatına biçimlendirmeye özen gösterdiğini belirtir. POSTbu durumda , belirtilen HTTP istek yöntemiyle belirtilen hedef konuma . Biz girerseniz 1içine firstNumbergiriş alanına ve 2içine secondNumbergiriş alanı, tarayıcı bir temsilini oluşturur firstNumber=1&secondNumber=2ve hedef kaynağın gerçek isteğinin vücut yükü olarak bu göndermek.
Bu nedenle sunucuya verilen ham HTTP isteği aşağıdaki gibi görünebilir:
POST /../someResource
Host: www.acme.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 28
Accept: application/html
firstNumber=1&secondNumber=2
Sunucu, hesaplamayı gerçekleştirebilir ve istemcinin bu biçimi anladığını belirttiği gibi, hesaplamanın sonucunu içeren başka bir HTML sayfasıyla yanıt verebilir.
Breton'un zaten işaret ettiği gibi, "RESTful" URL veya URI diye bir şey yoktur. Bir URI / URL kendi türünde bir şeydir ve bir müşteriye / kullanıcıya herhangi bir anlam ifade etmemelidir. Yukarıdaki hesap makinesi örneğinde bir kullanıcı verilerin nereye gönderileceği ile ilgilenmez, sadece giriş girdi alanını tetikledikten sonra talebin gönderilmesi ile ilgilenir. Görevi gerçekleştirmek için gereken tüm bilgiler sunucu tarafından zaten verilmelidir.
Bir tarayıcı ayrıca, isteğin aslında bazı giriş parametreleriyle bir hesap makinesi beslediğinin farkında olmayabilir, aynı zamanda sipariş sürecine devam etmek için sadece bir sonraki form temsilini döndüren bir tür sipariş formu veya tamamen farklı bir tür olabilir. kaynak. Böyle bir durumda HTML spesifikasyonunun talep ettiği şeyi yerine getirir ve sunucunun gerçekte ne yaptığını daha az umursamazdı. Bu kavram, bir tarayıcının, tercih ettiğiniz çevrimiçi mağazadan bazı şeyler sipariş etme, en iyi arkadaşlarınızla sohbet etme, çevrimiçi bir hesapta oturum açma vb. Gibi her türlü şeyi yapmak için aynı temsil biçimini kullanmasını sağlar.
Affordance böyle bazı öğelerin giriş alanı genellikle düğme olarak oluşturulur durumda, ne onunla hiç gerektiği tanımlarınızı gönderin. Bir düğme veya bağlantı söz konusu olduğunda, temel olarak onu tıklatmanızı söyler. Diğer unsurlar farklı mallar taşıyabilir. Böyle bir değerleme, bağlantı ilişkileri yoluyla da ifade edilebilir, yani preloadtemel olarak bir müşteriye, kullanıcı büyük olasılıkla bu içeriği daha sonra alacağı için bağlı kaynağın içeriğini arka planda yükleyebileceğini söyleyen açıklamalı bağlantılar ile ifade edilebilir. Bu bağlantı ilişkileri elbette standartlaştırılmalı veya Web bağlantısıyla tanımlanan ilişki türleri için genişletme mekanizmasını takip etmelidir .
Bunlar Web'de kullanılan ve REST mimarisinde de kullanılması gereken temel kavramlardır. "Bob Amca" Robert C. Martin'e göre bir mimari niyetle ilgilidir ve REST mimarisinin arkasındaki niyet , istemcileri kırmaktan korkmadan sunucuların gelecekte özgürce gelişebilmeleri için sunuculardan istemcilerin ayrıştırılmasıdır. Maalesef bu, çok fazla disiplin gerektiriyor çünkü kaplin tanıtmak veya işi yapmak ve devam etmek için hızlı çözüm üretmek çok kolay. Jim Webber'in bir REST mimarisinde işaret ettiği gibi, bir hizmet sağlayıcı olarak, müşterilerin bir sürecin sonuna kadar takip edecekleri 70'lerin metin tabanlı bir bilgisayar oyununa benzer bir etki alanı uygulama protokolü tasarlamaya çalışmalısınız .
Ne yazık ki gerçekte "REST" API'lerinin bolca yaptığı şey, bunun dışında her şeydir. Genellikle dinamik olarak entegre edilmesi zor olan, API'ya özgü harici belgelerde belirtilen çoğunlukla JSON tabanlı veri alışverişini görürsünüz. Bir isteğin nasıl görünmesi gerektiği biçimi de harici belgelere sabit olarak kodlanır ve bu da URI'leri önceden tanımlanmış tipler döndürecek şekilde yorumlayan çok sayıda uygulamaya yol açarönceden müzakere edilen bazı ortak temsil formatlarını kullanmak yerine. Bu, istemciler artık önceden tanımlanmış URI'ler için belirli bir veri biçimi (not gösterim biçimi değil!) Almayı beklediğinden sunucuların değişmesini önler. Bu özel veri biçimi değişimi ayrıca "veri biçimi" genellikle belirli bir API'ye geldiği için istemcilerin diğer API'larla etkileşime girmesini önler. Geçmişten bu kavramı, Peppol yakın zamanda AS2'yi varsayılan transfer protokolü olarak AS4 ile değiştirerek yeniden hareket etmesine rağmen, bir şekilde kötü olarak kınadığımız Corba, RMI veya SOAP gibi RPC teknolojilerinden geçmişten biliyoruz.
Sorulan asıl soru ile ilgili olarak, verileri csv dosyası olarak göndermek, application/x-www-form-urlencodedtemsil veya benzeri şeyleri kullanmaktan farklı değildir . Jim Webber, sonuçta HTTP'nin yalnızca uygulama etki alanı Web üzerinden belgelerin aktarılması olan bir aktarım protokolü olduğunu açıkça belirtti . İstemci ve sunucu text/csv, RFC 7111'de tanımlandığı gibi en azından her ikisini de desteklemelidir . Bu CSV dosyası, form öğelerini, isteği göndermek için bir hedef öğeyi veya özniteliği ve yapılandırmanın yüklenmesini gerçekleştirmek için HTTP yöntemini tanımlayan bir ortam türünün işlenmesinin bir sonucu olarak oluşturulabilir.
HTML , HAL Formları , halform , ion veya Hydra gibi formları destekleyen birkaç medya türü vardır . Şu anda, giriş verilerini otomatik olarak text/csvdoğrudan kodlayabilen bir medya türünün farkında değilim, bu yüzden IANA'nın medya türü kayıt defterine tanımlanması ve kaydedilmesi gerekebilir .
Tüm parametre setinin yüklenmesi ve indirilmesi sanırım bir sorun olmamalı. Daha önce de belirtildiği gibi, bir istemci işlemek üzere yeni içerik almak için URI'yi kullanacağı için hedef URI önemli değildir. İşletme tarihine göre filtreleme de zor olmamalıdır. Ancak burada sunucu, istemcinin seçebileceği tüm olanaklara sahip olmalıdır. Son yıllarda, filtrelenmiş bir yanıt almak için belirli bir uç noktada hedeflenebilen SQL benzeri bir dil tanıtan GraphQL ve RestQL gelişti. Bununla birlikte, gerçek bir REST anlamında bu, REST'in arkasındaki fikri ihlal etmektedir: a) GraphQL yani önbelleklemenin en iyi şekilde kullanılmasını bir şekilde önleyen tek bir uç nokta kullanır ve b) mevcut alanların upfrong bilgisini gerektirir, bu da müşterilerin birleştirilmesine neden olabilir kaynağın temel veri modeline.
Belirli yapılandırma parametrelerini etkinleştirmek veya devre dışı bırakmak, bu uygunluğu sağlayan hiper ortam kontrollerini tetiklemekle ilgilidir. HTML formlarında bu basit bir onay kutusu veya bir listede veya bu türde çok satırlı bir seçim olabilir. Forma ve hangi yöntemi tanımladığına bağlı olarak, tüm yapılandırmayı potansiyel olarak gönderebilir PUTveya yapılan değişiklikler hakkında akıllı olabilir ve yalnızca üzerinden kısmi bir güncelleme gerçekleştirebilir PATCH. İkincisi, temel olarak güncellenen değişiklik gösteriminin bir hesaplamasını gerektirir ve sunucuyu, mevcut gösterimi arzu edilene dönüştürmek için gerekli adımlarla besler. PATH spesifikasyonuna göre, bu işlemlerin içinde ya da hiçbirinin uygulanmaması için bir işlem içinde yapılmalıdır.
HTTP, bir sunucunun, değişiklikleri uygulamadan önce alınan bir isteği önceden doğrulamasına izin verir ve teşvik eder. İçin PUT Spec devletler:
Kaynak sunucu PUT temsilinin, sunucunun hedef kaynak için PUT tarafından değiştirilemeyecek veya değiştirilemeyecek kısıtlamalarla tutarlı olduğunu doğrulamalıdır. Bu, özellikle kaynak sunucu, GET yanıtlarında temsil meta verilerinin değerlerini ayarlamak için URI ile ilgili dahili yapılandırma bilgilerini kullandığında önemlidir. Bir PUT temsili hedef kaynakla tutarsız olduğunda, kaynak sunucu, temsili dönüştürerek veya kaynak yapılandırmasını değiştirerek bunları tutarlı hale getirmeli veya temsilin neden uygun olmadığını açıklamak için yeterli bilgi içeren uygun bir hata iletisiyle yanıt vermelidir. 409 (Çakışma) veya 415 (Desteklenmeyen Ortam Türü) durum kodları önerilir,
Örneğin, hedef kaynak her zaman "Metin / html" içerik türüne sahip olacak şekilde yapılandırılmışsa ve PUT olan temsilin "Görüntü / jpeg" içerik türüne sahip olması durumunda, kaynak sunucunun aşağıdakilerden birini yapması gerekir:
a. hedef kaynağı yeni ortam türünü yansıtacak şekilde yeniden yapılandırın;
b. PUT temsilini, yeni kaynak durumu olarak kaydetmeden önce kaynağınkine uygun bir biçime dönüştürmek; veya,
c. 415 (Desteklenmeyen Medya Türü) yanıtıyla, hedef kaynağın "metin / html" ile sınırlı olduğunu, belki de yeni gösterim için uygun bir hedef olabilecek farklı bir kaynağa bağlantı da içerdiğini belirten isteği reddetmek.
HTTP, bir PUT yönteminin, kullanıcı aracısı isteğinin amacı ve kaynak sunucu yanıtının anlamıyla ifade edilebilenin ötesinde bir kaynak sunucunun durumunu tam olarak nasıl etkilediğini tanımlamaz. ...
Bu postayı özetlemek için, bir istemciye gerekli veya desteklenen giriş parametreleri, isteği gönderilecek hedef konum, kullanılacak işlem ve medya türü hakkında bilgi vermenizi sağlayan mevcut bir medya türü kullanmalısınız. istek biçimlendirilmeli veya IANA'ya kaydettirdiğiniz kendi isteğinizi tanımlamalısınız. Girdiyi dönüştürmek istiyorsanız, ikincisi gerekli olabilirtext/csvve ardından CSV sunumunu sunucuya yükleyin. Doğrulama, değişiklikler kaynağa uygulanmadan önce gerçekleşmelidir. Gerçek URI, talebin nereye gönderileceğini belirlemek dışında müşteriler tarafından uygun olmamalıdır ve bu nedenle servis uygulayıcısı tarafından sizin tarafınızdan serbestçe seçilebilir. Bu adımları uygulayarak, sunucu tarafınızı istediğiniz zaman değiştirme özgürlüğüne sahip olursunuz ve istemciler, kullanılan ortam türlerini destekliyorlarsa sonuç olarak kırılmazlar.