La API Sun Cloud en http://kenai.com/projects/suncloudapis/pages/Home es un buen ejemplo a seguir para una API RESTful. Fiel a los principios REST, cuando obtienes un recurso, obtienes ni más ni menos que una representación de ese recurso.Mimetypes para una API RESTful
El encabezado Content-Type en la respuesta te dice exactamente cuál es el tipo de ese recurso, por ejemplo application/vnd.com.sun.cloud.Snapshot + json. Sun ha registrado estos tipos de miméticos con IANA.
¿Qué tan práctico es esto en general actualmente? La mayoría de las API que he visto han usado el tipo de contenido de "application/json". Esto le dice que la respuesta es JSON, pero nada más al respecto. Debe tener algo en el objeto JSON, como una propiedad "tipo", para saber de qué se trata.
Estoy diseñando una API RESTful (que no se hará pública, por lo tanto, no estaría registrando mimetypes). He estado utilizando RESTEasy y encuentro que incluso si especifico un tipo mimet completo, Content-Type en el encabezado de respuesta será exactamente lo que especificó el encabezado de la solicitud de aceptación. Si la solicitud solicita "application/* + json" de forma predeterminada, el encabezado de respuesta tendrá "application/* + json". Probablemente pueda solucionar esto cambiando el encabezado antes de que la respuesta se apague, pero ¿debería intentar hacer eso? ¿O debería la respuesta tener un comodín como lo hizo la solicitud?
¿O debería simplemente servir "application/json" como parece hacer la mayoría de las API?
pensamientos adicionales agregados más adelante:
Otra forma de expresar la pregunta es: ¿Debo utilizar HTTP como protocolo, o debería utilizar HTTP sólo como un mecanismo de transporte de envolver mi propio protocolo?
Para utilizar HTTP como protocolo, el cuerpo de entidad de la respuesta contiene la representación del objeto solicitado (o la representación de un objeto de mensaje de error), el encabezado "Content-Type" contiene el tipo exacto del objeto, y el encabezado "Estado" contiene un código de éxito o error.
Para usar HTTP como meramente un mecanismo de transporte, el encabezado "Estado" siempre se establece en 200 OK, el "Tipo de contenido" es algo genérico como "aplicación/json", y el cuerpo de la entidad contiene algo que sí tiene un objeto, un tipo de objeto, un código de error y cualquier otra cosa que desee. Si su propio protocolo es RESTful, entonces el esquema completo es RESTful. (HTTP es un protocolo RESTful, pero no el único posible.)
Su propio protocolo será opaco para todas las capas de transporte. Si usa HTTP como protocolo, todas las capas de transporte lo entenderán y pueden hacer cosas que no desea; por ejemplo, un navegador interceptará una respuesta "401 no autorizado" y mostrará un cuadro de diálogo de inicio de sesión, incluso si quiere manejarlo usted mismo.
Un problema que tengo con un cliente web es la interceptación del navegador de los códigos y encabezados de estado HTTP. Por ejemplo, si devuelve un 401 no autorizado, el cliente de JavaScript no lo ve antes de que el navegador lo agarre y coloque su propio cuadro de diálogo de inicio de sesión. A partir de ese momento, el navegador coloca su propio encabezado de Autorización en cada solicitud. Los Mimetypes pasan por OK, pero al menos un código de estado (401) es un problema. –