Una gran cantidad de lo que pensé que sabía sobre REST aparentemente está mal, y no estoy solo. Esta pregunta tiene una larga introducción, pero parece necesaria porque la información está un poco dispersa. La pregunta real viene al final si ya está familiarizado con este tema.
Desde el primer párrafo de las API REST de Roy Fielding deben estar impulsadas por hipertexto , está bastante claro que él cree que su trabajo está siendo ampliamente malinterpretado:
Me frustra la cantidad de personas que llaman a cualquier interfaz basada en HTTP una API REST. El ejemplo de hoy es la API REST de SocialSite . Eso es RPC. Grita RPC. Hay tanto acoplamiento en exhibición que debería recibir una calificación X.
Fielding continúa enumerando varios atributos de una API REST. Algunos de ellos parecen ir en contra de la práctica común y los consejos comunes en SO y otros foros. Por ejemplo:
Se debe ingresar una API REST sin conocimiento previo más allá del URI inicial (marcador) y un conjunto de tipos de medios estandarizados que son apropiados para la audiencia prevista (es decir, se espera que los comprenda cualquier cliente que pueda usar la API). ...
Una API REST no debe definir jerarquías o nombres de recursos fijos (un acoplamiento obvio de cliente y servidor). ...
Una API REST debería dedicar casi todo su esfuerzo descriptivo a definir los tipos de medios utilizados para representar recursos y controlar el estado de la aplicación, o definir nombres de relaciones extendidas y / o marcas habilitadas para hipertexto para tipos de medios estándar existentes. ...
La idea de "hipertexto" juega un papel central, mucho más que la estructura URI o lo que significan los verbos HTTP. "Hipertexto" se define en uno de los comentarios:
Cuando yo [Fielding] digo hipertexto, me refiero a la presentación simultánea de información y controles de manera que la información se convierte en la posibilidad a través de la cual el usuario (o autómata) obtiene opciones y selecciona acciones. Hypermedia es solo una expansión de lo que significa el texto para incluir anclajes temporales dentro de un flujo de medios; la mayoría de los investigadores han abandonado la distinción.
El hipertexto no necesita ser HTML en un navegador. Las máquinas pueden seguir enlaces cuando comprenden el formato de datos y los tipos de relaciones.
Supongo que en este punto, pero los dos primeros puntos anteriores parecen sugerir que la documentación de API para un recurso de Foo que se parece a lo siguiente conduce a un acoplamiento estrecho entre el cliente y el servidor y no tiene lugar en un sistema RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
En cambio, un agente debería verse obligado a descubrir los URI de todos los Foos, por ejemplo, emitiendo una solicitud GET contra / foos. (Esos URI pueden seguir el patrón anterior, pero eso no viene al caso). La respuesta utiliza un tipo de medio que es capaz de transmitir cómo acceder a cada elemento y qué se puede hacer con él, dando lugar al tercer punto anterior. . Por este motivo, la documentación de la API debe centrarse en explicar cómo interpretar el hipertexto contenido en la respuesta.
Además, cada vez que se solicita un URI a un recurso de Foo, la respuesta contiene toda la información necesaria para que un agente descubra cómo proceder, por ejemplo, accediendo a los recursos asociados y principales a través de sus URI, o tomando medidas después de la creación. / eliminación de un recurso.
La clave de todo el sistema es que la respuesta consiste en hipertexto contenido en un tipo de medio que transmite a sí mismo al agente opciones para continuar. No es diferente a la forma en que funciona un navegador para los humanos.
Pero esta es mi mejor suposición en este momento en particular.
Fielding publicó un seguimiento en el que respondió a las críticas de que su discusión era demasiado abstracta, carente de ejemplos y rica en jerga:
Otros intentarán descifrar lo que he escrito de maneras que sean más directas o aplicables a alguna preocupación práctica de hoy. Probablemente no lo haga, porque estoy demasiado ocupado lidiando con el próximo tema, preparándome para una conferencia, escribiendo otro estándar, viajando a algún lugar distante o simplemente haciendo las pequeñas cosas que me hacen sentir que me he ganado mi sueldo.
Entonces, dos preguntas simples para los expertos en REST con una mentalidad práctica: ¿cómo interpretas lo que dice Fielding y cómo lo pones en práctica al documentar / implementar API REST?
Editar: esta pregunta es un ejemplo de lo difícil que puede ser aprender algo si no tienes un nombre para lo que estás hablando. El nombre en este caso es "Hypermedia como motor del estado de la aplicación" (HATEOAS).