¿Cuál es la necesidad de 'capacidad de descubrimiento' en una API REST cuando los clientes no están lo suficientemente avanzados como para usarla de todos modos?

Las diversas charlas que he visto y los tutoriales que escaneé en REST parecen enfatizar algo llamado 'capacidad de descubrimiento'. A mi entender limitado, el término parece significar que un cliente debería poder ir http://URLy obtener automáticamente una lista de las cosas que puede hacer.

Lo que me cuesta entender es que los "clientes de software" no son seres humanos. Son solo programas que no tienen el conocimiento intuitivo para entender exactamente qué hacer con los enlaces provistos. Solo las personas pueden ir a un sitio web y entender el texto y los enlaces presentados y actuar en consecuencia.

Entonces, ¿cuál es el punto de descubrimiento, cuando el código del cliente que accede a tales URL detectables en realidad no puede hacer nada con él, a menos que el desarrollador humano del cliente realmente experimente con los recursos presentados? Esto parece exactamente lo mismo que definir el conjunto de funciones disponibles en un manual de Documentación, solo desde una dirección diferente y en realidad implica más trabajo para el desarrollador. ¿Por qué este segundo enfoque de predefinir lo que se puede hacer en un documento externo a los recursos REST reales se considera inferior?

La necesidad de capacidad de detección puede no ser relevante, pero los enlaces que permiten la capacidad de detección sirven para más propósitos. El más importante de estos, en mi opinión, es que proporcionar URI completos en las respuestas al cliente, significa que ningún cliente tendrá que "componer" un URI. Eso significa que ningún cliente necesitará nunca saber cómo se estructuran los URI. Y eso a su vez permite a los desarrolladores del servidor cambiar el esquema de URI siempre que les convenga, ya que no necesitan considerar a los clientes más antiguos que todavía dependen de una antigua forma de estructurar los URI.

Puede que los "clientes" no estén lo suficientemente avanzados como para usarlo, pero los usuarios de los clientes sí pueden hacerlo. Un cliente puede ser algo tan simple como un navegador web, después de todo. La capacidad de detección se trata de permitir que las personas aprendan y usen la API .

Por ejemplo, Jenkins (el servidor CI) tiene una interfaz similar a REST. Vaya a cualquier página, pegue la URL con "/ api" y obtendrá una página que describe todo lo que puede hacer. Hace que aprender la API sea trivial. Por ejemplo, http://ci.jruby.org lo lleva al servidor jenkins para jruby, y http://ci.jruby.org/api lo lleva a la api para esa página específica.

Hace un tiempo tuve el placer de trabajar con una API que tenía documentación que era muy, muy difícil de entender.

Una vez que logré obtener una respuesta real del servidor, fue posible comparar la documentación con la respuesta del servidor y usarla para descifrar la documentación (y sí, descifrarlo era el término correcto). El problema era que si se enviaba una solicitud al servidor que no era exactamente correcta de acuerdo con las especificaciones, solo obtendría un error, y con la documentación ilegible, descubrir cómo enviar las solicitudes correctas era casi imposible. También había diferentes versiones de la documentación de la API que no estaban de acuerdo entre sí y probablemente no estaban de acuerdo con la API en sí; Eso no ayudó.

Si hubiera habido un comando que pudiera enviar al servidor, devolviendo una lista de todos los comandos posibles y cómo enviarlos exactamente, eso habría sido extremadamente útil. La capacidad de descubrimiento no es solo para los clientes, también es útil para los desarrolladores de software.

NOTA: No soy un experto en el tema, pero pasé por un proceso similar de tratar de conciliar los diferentes matices de las interpretaciones de la gente de "REST" hace unos años, y esta es la conclusión que obtuve al investigarlo. hora.

A mi entender, esto se deriva de Hypermedia de Roy Fielding como el motor del estado de la aplicación, también conocido como "HATEOAS", que luego se convierte en un habilitador de la idea de una "web semántica".

Entonces ... básicamente, y nuevamente, según tengo entendido, usted hace que su aplicación RESTful se describa a sí misma de manera tal que el consumidor no tenga que tener conocimiento previo de un contrato formal para consumir su contenido / funcionalidad. Son capaces de interactuar desde un punto final raíz predeterminado y luego recorrer enlaces contextualmente relevantes que su aplicación proporciona a medida que el consumidor interactúa. El consumidor, por supuesto, puede ser una persona o un agente sistémico.

Si solo está utilizando "REST" para urls bonitas asignadas a operaciones CRUD de las que un consumidor debe tener conocimiento previo y llamadas de acuerdo con un contrato bien conocido, Roy Fielding consideraría que no es realmente RESTful.

Eso no quiere decir que una configuración de servicio RPC con sabor REST no pueda ser útil / una mejora sobre un modelo RPC más elaborado y adecuado para un uso limitado / controlado, pero los intransigentes lo mirarán de reojo y lo considerarán degenerado / no realmente DESCANSO.