Sto progettando correttamente questa interfaccia REST di WCF?

Question

Sto creando un servizio web WCF con il servizio di autenticazione WcF e il primo set di funzioni necessario è la gestione di una casella di posta in arrivo per un client. Il client sarà determinato dall'autenticazione.

Questo è il mio tentativo di un design RESTful delle API:

---

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

restituisce una pagina dei risultati nel casella di posta con un filtro di ricerca opzionale applicato

• Conte - numero di record per pagina
• Pagina - pagina iniziale
• Sort - campo (opzionale) per ordinare il
• Ricerca - (opzionale) testo da cercare

---

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

Marks uno o più messaggi letti o non letti

• Azione - MarkRead o MarkUnread
• MessageIDs - elenco di ID messaggio per contrassegnare

---

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

Archives uno o più messaggi

• MessageIDs - lista dei messaggi per archiviare gli ID

---

Sto facendo questo diritto? In caso contrario, quale sarebbe un modo migliore per progettare questa interfaccia?

Answer 1

Riguardo alla parte letta/non letta Non penso che sia necessario un post. Penso che è necessario mettere metodo https://api.mydomain.com/v1/inbox/messageId/Read https://api.mydomain.com/v1/inbox/messageId/Unread

Messaggio necessario quando si crea un nuovo record e si desidera aggiornare

per Archive parte I sono d'accordo. Ricorda solo di restituire i risultati per il processo di archiviazione.

Answer 2

POST di Roy è utile quando di fronte a queste domande: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

qui: focus sulla definizione del tipo di supporto (s) invece di accoppiare i vostri clienti a gruppi predefiniti di URI. Non hanno bisogno di essere registrati, per essere utili, a proposito.

Forse anche vedere http://www.nordsc.com/ext/classification_of_http_based_apis.html#http-type-one

Answer 3

Martin Fowler ha un good summary del Maturity Model Richardson e quello che serve per rendere un servizio RESTful. Jan ha fatto riferimento a uno dei post di Roy Fielding, ma ci sono alcuni passaggi da seguire oltre a hypermedia (e HATEOAS).

Con riferimento allo Richardson model, penso che la vostra API necessiterebbe di alcune modifiche per arrivare a "Livello 3" (duh duh duhhhh). La collezione /v1/inbox/messages sembra valida e il solo supporto di GET indica che si tratta di una risorsa di sola lettura per l'utente. Tuttavia, le azioni e gli ID e /v1/inbox/archive sono solo tunneling di servizi in stile RPC su HTTP - "Livello 0" nel numero article.

Io suggerirei qualcosa come il seguente come un ingenuo, non ipermedia (cioè "Livello 2") API:

• per recuperare un elenco di informazioni di riepilogo di tutti i messaggi (in tutte le cartelle):

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

  risposta:

  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> 
  

• di recuperare un messaggio completo:

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

  Risposta:

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

• Per modificare un messaggio (ad esempio, a segnare come letto e spostarlo nella cartella di archivio):

  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" /> 
  

  Nota: qui sto intenzionalmente usando POST invece di PUT per indicare un aggiornamento parziale.

Altre cose che si distinguono come bisognose di attenzione sono: risposte

• Hypermedia e multimediali tipi. Francamente questo è meglio spiegato da altri (ad esempio il libro REST In Practice o lo InfoQ Coffee Cup example dagli stessi autori), ma in breve le vostre risposte dovrebbero indicare al cliente quali altre azioni potrebbero essere possibili dalla risposta alla loro richiesta più recente e consentire loro per scoprire l'intera API da un singolo URI. Ad esempio, vi è un'implicazione delle raccolte di cartelle sopra. Se GET /v1/messages/1234 restituito:

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

  allora il cliente avrebbe un esempio concreto di un URI provare un OPTIONS su, e una buona idea di quello che potrebbe essere lì.

• Codici di risposta e contenuto: 200 OK è ovvio. Rispondere con 403 Forbidden se l'utente non è autorizzato a visualizzare un particolare messaggio, 404 Not Found se l'ID messaggio non esiste. Ogni volta che restituisci un errore, dai al cliente alcune indicazioni su come correggere la richiesta (se possibile).