¿Estoy diseñando correctamente esta interfaz WCF RESTful?

Question

Estoy creando un servicio web WCF con WcF Authentication Service y el primer conjunto de funciones que necesito es administrar una bandeja de entrada para un cliente. El cliente será determinado por la autenticación.

Ésta es mi tentativa en un diseño de REST de la API:

---

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

devuelve una página de resultados en la bandeja de entrada con un filtro de búsqueda opcional aplicada

• Conde - número de registros por página
• Página - página para comenzar en
• Ordenar - campo (opcional) para ordenar el
• Buscar - (opcional) texto a buscar

---

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

Marcas uno o más mensajes leídos o no leídos

• Acción - MarkRead o MarkUnread
• ID de mensaje - lista de ID de mensaje para marcar

---

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

Archivos uno o más mensajes

• messageids - lista de identificadores de mensaje para archivar

---

estoy haciendo esto correcto? Si no, ¿cuál sería una mejor manera de diseñar esta interfaz?

Answer 1

En cuanto a la parte de lectura/no leída No creo que necesite una publicación. Creo que se necesita método https://api.mydomain.com/v1/inbox/messageId/Read https://api.mydomain.com/v1/inbox/messageId/Unread

Mensaje necesarios cuando se crea un nuevo registro de peso y que desea actualizar

Por parte I Archivo estoy de acuerdo Solo recuerda devolver el resultado para el proceso de archivo.

Answer 2

POST del Roy es útil cuando se enfrentan a este tipo de preguntas: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Por lo tanto: se centran en la definición de tipo (s) de memoria en lugar de acoplar sus clientes a conjuntos predefinidos de URIs. No necesitan registrarse, para ser útiles, por cierto.

Tal vez también ver http://www.nordsc.com/ext/classification_of_http_based_apis.html#http-type-one

Answer 3

Martin Fowler tiene una good summary del Modelo de Madurez Richardson y lo que se necesita para hacer un servicio REST. Jan hizo referencia a una de las publicaciones de Roy Fielding, pero hay algunos pasos a tener en cuenta además de hipermedia (y HATEOAS).

Con referencia al Richardson model, creo que su API necesitaría algunos cambios para llegar al "Nivel 3" (duh duh duhhhh). La colección /v1/inbox/messages parece sólida, y solo admite GET indica que es un recurso de solo lectura para el usuario. Sin embargo, POST acciones de compra e ID a /v1/inbox/mark y /v1/inbox/archive solo está haciendo un túnel de servicios de estilo RPC a través de HTTP - "Nivel 0" en el article.

me gustaría sugerir algo como lo siguiente como una, no ingenua hipermedia (es decir, "Nivel 2") de la API:

• Para recuperar una lista de información de resumen de todos los mensajes (en todas las carpetas):

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

  Respuesta:

  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> 
  

• para recuperar un mensaje completo:

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

  Respuesta:

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

• Para editar un mensaje (por ejemplo, para marcarlo como leído y moverlo a la carpeta de archivo):

  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: aquí estoy usando intencionalmente POST en lugar de PUT para indicar una actualización parcial.

Otras cosas que se destacan como que requieren atención son: Respuestas

• Hipermedia y tipos de medios. Francamente, esto es mejor explicado por otros (por ejemplo, el REST In Practice libro, o el InfoQ Coffee Cup example por los mismos autores), pero en resumen, sus respuestas deben indicar al cliente qué otras acciones podrían ser posibles a partir de la respuesta a su solicitud más reciente y permitirles para descubrir toda la API desde solo un URI. Como ejemplo, hay una implicación de colecciones de carpetas arriba. Si GET /v1/messages/1234 devueltos:

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

  continuación, el cliente tendría un ejemplo concreto de un URI para tratar una OPTIONS en adelante, y una buena idea de lo que podría estar allí.

• Códigos de respuesta y contenido: 200 OK es obvio. Responda con 403 Forbidden si el usuario no está autorizado para ver un mensaje en particular, 404 Not Found si el ID del mensaje no existe. Cada vez que devuelve un error, déle al cliente alguna indicación de cómo corregir su solicitud (si es posible).