Bu WCF RESTful arayüzünü doğru tasarlıyor muyum?

Question

WcF Kimlik Doğrulama Hizmeti ile bir WCF web hizmeti oluşturmaktayım ve ihtiyacım olan ilk işlev kümesi bir istemci için gelen kutusunu yönetmek. Müşteri kimlik doğrulama ile belirlenecektir.

Bu API dinlendirici tasarımı benim girişimi:

---

https://api.mydomain.com/v1/inbox/messages (GET)

opsiyonel arama filtresi ile gelen kutusundaki sonuçlarının bir sayfayı döndürür

• Sayısı uygulanan - sayfa başına kayıt sayısı
• Sayfa - sayfa başlangıcında
• Sıralama - Bir veya daha fazla mesaj okumak

---

aramak için (isteğe bağlı) Metin

https://api.mydomain.com/v1/inbox/mark (POST)

Marks veya okunmamış

- (opsiyonel) alan
• Search sıralamak
• Action - MarkOğumunu veya İşaretiniAnal
• MessageIDs - işaretlenecek Mesaj Kimlikleri listesi

---

https://api.mydomain.com/v1/inbox/archive (POST)

Arşivler, bir veya daha fazla mesaj

• MessageIDs -

---

bunu doğru yapıyor muyum arşivlemek için mesaj kimlikleri listesi? Değilse, bu arayüzü tasarlamanın daha iyi bir yolu ne olurdu?

Answer 1

Okunması/okunmamış bölümle ilgili Bir gönderiye ihtiyacınız olduğunu düşünmüyorum. Sana koymak yeni bir kayıt oluştururken https://api.mydomain.com/v1/inbox/messageId/Read

Mesaj gerekli https://api.mydomain.com/v1/inbox/messageId/Unread yöntemini gerek ve arşiv bölümü I için

güncellemek istiyorum katılıyorum Sadece arşivleme sürecinin sonucunu geri almayı unutmayın.

Answer 2

tür sorular karşılaşıldığında Roy'un POST faydalıdır: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Dolayısıyla: yerine URI'lerinin önceden tanımlanmış müşterilerinize bağlanması ortam türü (ler) tanımlayan odaklanın. Yararlı olmak için kayıt edilmeleri gerekmiyor, BTW.

Belki de http://www.nordsc.com/ext/classification_of_http_based_apis.html#http-type-one

Answer 3

Martin Fowler Richardson Olgunluk Modeli ve ne dinlendirici bir hizmet yapmak için gereken bir good summary sahiptir görüyoruz. Jan, Roy Fielding'in gönderilerinden birine atıfta bulundu, ancak hiper ortamın yanı sıra dikkat edilmesi gereken bazı adımlar var (ve HATEOAS).

Richardson model referansıyla, API'nizin "Seviye 3" e (duh duh duhhhh) ulaşmak için bazı değişikliklere ihtiyaç duyacağını düşünüyorum. /v1/inbox/messages koleksiyonu ses görünüyor ve sadece GET desteği, kullanıcının salt okunur bir kaynak olduğunu belirtir. Ancak POST eylemleri ve /v1/inbox/mark ve /v1/inbox/archive numaralı kimlikler yalnızca HTTP üzerinden RPC stili hizmetlerin tünelini oluşturur - article'daki "Düzey 0".

Ben naif olmayan hiperortam olarak aşağıdaki gibi bir şey öneririm (yani "Düzey 2") API:

• tüm iletilerin özeti bilgilerin bir listesini almak için (içinde tüm klasörler):

  GET /v1/messages HTTP/1.1 
  Host: api.mydomain.com 
  

  Yanıt:

  content-type: text/xml 
  
  <?xml version="1.0"?> 
  <messages> 
      <message subject="Subject" unread="true" id="1234" folder="inbox" /> 
      <message subject="Hello, world" unread="false" id="24" folder="inbox" /> 
      ... 
  </messages> 
  

• tam mesajı almak için:

  GET /v1/messages/1234 HTTP/1.1 
  Host: api.mydomain.com 
  

  Yanıt:

  content-type: text/xml 
  
  <?xml version="1.0"?> 
  <message subject="Subject" unread="true" id="1234" folder="inbox"> 
      Hi, this is the message. 
  </message> 
  

• Bir mesajı düzenlemek için (örneğin okumak ve arşiv klasöre taşıyın gibi) işaretlemek için:

  POST /v1/inbox/messages/1234 HTTP/1.1 
  Host: api.mydomain.com 
  content-type: text/xml 
  
  <?xml version="1.0"?> 
  <message id="1234" unread="false" folder="archive" /> 
  

  Not: Burada ben kasıtlı kısmi güncelleştirme belirtmek için POST yerine PUT ait kullanıyorum. dikkat gerektiren olarak öne

Diğer şeyler şunlardır:

• Hiperortam yanıtları ve medya türleri. Açıkçası bu diğerleri tarafından daha iyi açıklanabilir (örneğin, REST In Practice kitap veya aynı yazarlar tarafından InfoQ Coffee Cup example), ancak kısacık cevaplarınız müşteriye, en son isteklerine verilen yanıttan başka hangi eylemlerin mümkün olabileceğini belirtmeli ve onlara izin vermelidir. Tüm API'yi yalnızca tek bir URI'den keşfetmek. Örnek olarak, yukarıdaki klasör koleksiyonlarının bir anlamı vardır. GET /v1/messages/1234 döndürdüyse:

  <message subject="Subject" unread="true" id="1234" folder="inbox" > 
      Message text here. 
  
      <link rel="folder" href="http://api.mydomain.com/v1/folders/inbox" /> 
  </message> 
  

  sonra istemci üzerinde OPTIONS ve orada ne olabileceğini iyi bir fikir denemek için bir URI somut bir örnek olurdu.

• Yanıt kodları ve içeriği: 200 OK aşikar. Kullanıcı belirli bir mesajı görüntüleme yetkisine sahip değilse, 403 Forbidden ile yanıtlayın, mesaj kimliği yoksa 404 Not Found. Her hata verdiğinizde, müşteriye, isteklerini nasıl düzelteceğine dair birtakım bilgiler verin (eğer mümkünse).