RESTful API'sinde komut desenini uygulama

Umarım olabildiğince RESTful hale getirmek için bir HTTP API tasarlama sürecindeyim.

İşlevselliğin birkaç kaynağa yayıldığı bazı eylemler vardır ve bazen geri alınması gerekir.

Kendi kendime düşündüm, bu bir komut kalıbına benziyor, ama onu bir kaynağa nasıl modelleyebilirim?

Böyle bir şeyle yaratılacak olan DepositAction gibi XXAction adında yeni bir kaynak tanıtacağım

POST /card/{card-id}/account/{account-id}/Deposit
AmountToDeposit=100, different parameters...

bu aslında yeni bir DepositAction oluşturur ve Do / Execute yöntemini etkinleştirir. Bu durumda, 201 Oluşturulan HTTP durumu döndürmek, işlemin başarıyla yürütüldüğü anlamına gelir.

Daha sonra bir müşteri eylem ayrıntılarına bakmak isterse

GET /action/{action-id}

Güncelleme / PUT bloke edilmelidir sanırım, çünkü burada alakalı değil.

Ve eylemi geri almak için kullanmayı düşündüm

DELETE /action/{action-id}

gerçekte ilgili nesnenin Geri Al yöntemini çağırır ve durumunu değiştirir.

Diyelim ki tek bir Do-Undo ile mutluyum, yeniden yapmam gerekmiyor.

Bu yaklaşım uygun mu?

Kullanılmaması gereken tuzaklar var mı?

Bu müşterilerin POV'sundan anlaşılıyor mu?

Kafa karıştırıcı bir soyutlama katmanı ekliyorsunuz

API'niz çok temiz ve basit bir şekilde başlar. Bir HTTP POST, verilen parametrelerle yeni bir Para Yatırma kaynağı oluşturur. Ardından, API'nın temel bir parçası olmaktan ziyade bir uygulama ayrıntısı olan "eylemler" fikrini tanıtarak raydan çıkıyorsunuz.

Alternatif olarak bu HTTP konuşmasını düşünün ...

POST / kart / {kart kimliği} / hesap / {hesap kimliği} / Para Yatırma

AmountToDeposit = 100, farklı parametreler ...

201 OLUŞTURULDU

Yer = / kart / 123 / hesap / 456 / Mevduat / 789

Şimdi bu işlemi geri almak istiyorsunuz (teknik olarak, dengeli bir muhasebe sisteminde buna izin verilmemeli, ne hey):

SİL / kart / 123 / hesap / 456 / Depozito / 789

204 İÇERİK YOK

API tüketicisi, bir Para Yatırma kaynağı ile uğraştığını bilir ve üzerinde hangi işlemlere izin verildiğini belirleyebilir (genellikle HTTP'deki OPTIONS aracılığıyla).

Silme işleminin uygulanması bugün "eylemler" yoluyla gerçekleştirilmesine rağmen, bu sistemi örneğin C # 'dan Haskell'e geçirdiğinizde ve ön ucu "ikincil" eylem kavramının değer katmaya devam edeceğinin garantisi yoktur oysa, temel depozito kavramı kesinlikle öyle.

DELETE ve Para Yatırma alternatifini kapsayacak şekilde düzenleyin

Bir silme işleminden kaçınmak, ancak yine de Para Yatırma işlemini etkili bir şekilde kaldırmak için aşağıdakileri yapmanız gerekir (Para Yatırma ve Para Çekme için genel bir İşlem kullanarak):

POST / kart / {kart kimliği} / hesap / {hesap kimliği} / İşlem

Tutar = -100 , farklı parametreler ...

201 OLUŞTURULDU

Yer = / kart / 123 / hesap / 456 / transation / 790

Tam tersi olan (-100) yeni bir İşlem kaynağı oluşturulur. Bu, hesabın tekrar 0'a dengelenmesi ve orijinal İşlemin reddedilmesi etkisine sahiptir.

Gibi bir "yardımcı program" bitiş noktası oluşturmayı düşünebilirsiniz

POST / kart / {kart kimliği} / hesap / {hesap kimliği} / İşlem / 789 / Geri al <- KÖTÜ!

aynı etkiyi elde etmek için. Bununla birlikte, bu bir URI'nin anlambilimini bir fiil ekleyerek tanımlayıcı olarak keser. Tanımlayıcılardaki isimlere sadık kalmak ve işlemleri HTTP fiilleriyle kısıtlı tutmak daha iyidir. Bu şekilde tanımlayıcıdan kolayca bir kalıcı bağlantı oluşturabilir ve GET'ler vb. İçin kullanabilirsiniz.

REST'in var olmasının temel nedeni ağ hatalarına karşı dayanıklılıktır. Hangi amaçla tüm operasyonlar idempotent olmalıdır .

Temel yaklaşım makul görünmektedir, ancak DepositActionyaratılışın tanımlanma şekliniz sabit olması gereken kasıtlı değildir. Sahip olarak istemci yinelenen istekleri tespit etmek için kullanılacak benzersiz bir kimlik sağlar. Böylece yaratılış

PUT /card/{card-id}/account/{account-id}/Deposit/{action-id}
AmountToDeposit=100, different parameters...

Daha önce aynı içerikle aynı URL'ye başka bir PUT yapılırsa, içerik aynı ise yanıt 201 created, içerik farklıysa yine de hata olmalıdır. Bu, istemcinin isteği başarısız olduğunda yeniden iletmesine izin verir, çünkü istemci isteğin veya yanıtın kaybolup kaybolmadığını söyleyemez.

PUT kullanmak daha mantıklıdır, çünkü sadece kaynağı yazar ve idempotenttir, ancak POST kullanmak da herhangi bir soruna neden olmaz.

İşlem ayrıntılarına bakmak için müşteri GETaynı URL'yi, yani

GET /card/{card-id}/account/{account-id}/Deposit/{action-id}

ve geri almak için Silebilir. Ama aslında örnekte görüldüğü gibi para ile ilgili bir şey varsa, ben bunun yerine hesap verebilirlik (oluşturulan ve iptal edilen işlem iz kalır kalır) yerine eklenen "iptal" bayrakları ile PUTting öneririz.

Şimdi benzersiz bir kimlik oluşturma yöntemi seçmeniz gerekiyor. Birkaç seçeneğiniz var:

1. Eklenmesi gereken exchange'de daha önce istemciye özgü öneki yayınlayın.
2. Sunucudan boş benzersiz kimlik almak için özel bir POST isteği ekleyin. Bu isteğin idempotent olması gerekmez (ve gerçekten olamaz), çünkü kullanılmayan kimlikler gerçekten herhangi bir soruna neden olmaz.
3. Sadece UUID kullanın. Herkes onları kullanıyor ve kimse MAC tabanlı olanlarla veya rastgele olanlarla herhangi bir sorun yaşamıyor gibi görünüyor.