"¿Y le creíste?" El ombudsman del casco dijo con reproche. "Bueno, ¿qué piensas, habría tomado estos pesos sin tu permiso?"
"¿Entonces tomaste las pesas?" Gritó Ostap. - por qué?
- Panikovsky dijo que son de oro.
Ostap miró a Panikovsky. Solo ahora se dio cuenta de que debajo de su chaqueta no había más que un frente de camisa de cincuenta dólares y desde allí la mirada desnuda de Dios miró a la luz del día. Sin una palabra, el gran combinador cayó en una silla. Él se sacudió, atrapando sus manos en el aire. Luego retumbaron ruidos volcánicos de su garganta, las lágrimas salieron de sus ojos y la risa, que afectó todo el cansancio de la noche, toda la decepción en la pelea con Koreiko, tan patéticamente parodiada por sus hermanos de leche.
Con este fragmento de los clásicos, me gustaría introducir la traducción de la publicación REST API de Roy T. Fielding. Las API REST deben estar basadas en hipertexto. Un agradecimiento especial a
habr.com/users/arthuriantech por el enlace al material.
Esta semana en Habré se marcó como la semana de REST (Full) API. En este sentido, siempre me confundió la presencia del prefijo REST en este término. Y, como resultó, no solo yo. Hoy lo leeré yo mismo e invitaré a todos a descubrir qué pensó Roy T. Fielding al respecto en 2008. Por supuesto, alguien se arrastra nerviosamente en un taburete y dice: dile a Roy, Benya lo sabe por la API REST. Sin embargo, comenzaremos.
Me desanima la idea de cuántas personas llaman a cualquier interfaz basada en el protocolo HTTP REST API. El ejemplo de hoy es la API REST SocialSite. Este es un RPC. Este es un RPC flagrante. Demuestra enlaces tan duros que es hora de que él asigne la categoría de porno duro.
¿Qué hay que hacer para que entiendan que el hipertexto es un elemento necesario en la arquitectura REST? En otras palabras, si el mecanismo de estado de la aplicación (y, por lo tanto, la API) no está basado en hipertexto, no puede ser RESTful y no puede ser una API REST. El punto ¿Qué libro debo reescribir para aclararlo?
Desarrolladores de API, preste atención a las siguientes reglas antes de llamar a sus creaciones de API REST:
La API REST no debe depender de un protocolo de comunicación específico, aunque su mapeo exitoso a este protocolo puede depender de la disponibilidad de metadatos, la elección de métodos, etc. En general, cualquier protocolo en un esquema URI debe permitir que se use cualquier esquema URI para la identificación. [El error aquí es que la identificación no está separada de la interacción.]
La API REST no debe contener ningún cambio en los protocolos de comunicación, excepto completar o corregir los detalles de bits de protocolos estándar insuficientemente definidos, como el método PATCH HTTP o el campo de encabezado de enlace. Las soluciones alternativas para implementaciones que no funcionan (como los navegadores que son lo suficientemente tontos como para creer que HTML define un conjunto de métodos HTTP) deben determinarse por separado o, al menos en las aplicaciones, con la expectativa de que la solución temporal eventualmente se vuelva obsoleta. [El error aquí es que las interfaces de recursos son específicas y no universales.]
La API REST debería dedicar casi todos sus esfuerzos descriptivos a definir los tipos de medios utilizados para representar los recursos y administrar el estado de la aplicación, así como a definir nombres de marcas y relaciones extendidas con soporte de hipertexto para los tipos de medios estándar existentes. Cualquier esfuerzo dedicado a describir qué métodos usar con qué URI de interés debe definirse completamente como parte de las reglas de procesamiento para el tipo de medio (y, en la mayoría de los casos, ya definido por los tipos de medios existentes). [El error aquí es que la información externa al recurso controla la interacción en lugar del hipertexto].
La API REST no debe definir nombres de recursos fijos o espacios de nombres (conectividad estrecha cliente-servidor). Los servidores deben tener la libertad de administrar sus propios espacios de nombres. En cambio, deje que los servidores instruyan a los clientes sobre cómo crear los URI apropiados, por ejemplo, en formularios HTML y plantillas de URI, definiendo estas instrucciones en tipos de medios y relaciones de referencia. [El error aquí es que la estructura del recurso se establece fuera de este recurso, por ejemplo, en un estándar específico de dominio, que en realidad es un análogo de la relación funcional RPC].
La API REST nunca debería tener recursos "escritos" importantes para el cliente. Los autores de las especificaciones pueden usar tipos de recursos para describir la implementación del servidor detrás de la interfaz, pero estos tipos deben ser irrelevantes e invisibles para el cliente. Los únicos tipos que son importantes para el cliente son el tipo de medio de la vista actual y los nombres de relación estandarizados. [ver arriba]
La API REST debe ingresarse sin ningún conocimiento previo que no sea el URI inicial y un conjunto de tipos de medios estandarizados adecuados para el público objetivo (es decir, esperado en el lado del cliente, que puede usar la API). A partir de este momento, todas las transiciones de los estados de la aplicación deben determinarse mediante la elección de las opciones proporcionadas por el servidor que están presentes en las vistas recibidas o por las manipulaciones del usuario con estas vistas. Las transiciones pueden ser determinadas (o limitadas) por el conocimiento del cliente de los tipos de medios y mecanismos de comunicación de recursos que pueden mejorarse sobre la marcha (por ejemplo, código a pedido). [El error aquí es que la información externa al recurso controla la interacción en lugar del hipertexto].
Tal vez me perdí algo, pero lo anterior son las reglas que son esenciales para el hipertexto, que se violan con mayor frecuencia en la llamada API REST. Intenta seguir con ellos o elige otra palabra de moda para tu API.
Esta publicación de Roy T. Fielding provocó una discusión en los comentarios. Propongo familiarizarme con la parte de la discusión, que fue acompañada por las respuestas del autor.
Pregunta:
¿En qué sentido usa el término "hipertexto" aquí? ¿Tengo que leer tu trabajo para entender lo que quieres decir, o hay algo en línea que revele el significado de este concepto?
La respuesta es:
Tengo una diapositiva en mi charla REST que explica lo que significa hipertexto (e hipermedia).
El hipertexto tiene muchas definiciones:
La definición inicial de Ted Nelson se centró en documentos no lineales.
Por "hipertexto" me refiero a un documento no lineal: un texto que se bifurca y permite al lector elegir, un documento que es fácil de leer en una pantalla interactiva. En general, se acepta que esta es una secuencia de bloques de texto unidos por enlaces que ofrecen al lector varias rutas. [Theodore H. Nelson]
El hipertexto luego se asoció con un mecanismo de interfaz de usuario específico.
El hipertexto es un medio de almacenamiento compatible con computadora en el que los documentos relacionados se muestran con sus enlaces en una pantalla de computadora de alta resolución. [Jeffrey Conklin]
Cuando digo "hipertexto", me refiero a la presentación simultánea de información y controles de tal manera que la información esté disponible, gracias a lo cual el usuario (o máquina) puede elegir y elegir acciones. Hypermedia es simplemente una extensión de lo que significa el texto para incluir anclas temporales en la secuencia de medios; La mayoría de los investigadores rechazaron esta distinción.
El hipertexto no tiene que ser HTML para el navegador. Las máquinas pueden seguir enlaces cuando entienden el formato de datos y los tipos de relación.
Dave Johnson (autor de la API criticada):
Tal vez le di una redacción borrosa. Nunca quise decir que las API de OpenSocial o SocialSite RPC eran RESTful. Más en mi blog rollerweblogger.org/roller/entry/the_x_rated_socialsite_api .
La respuesta es:
El protocolo RESTful de OpenSocial no es RESTful. Esto se puede solucionar con cambios relativamente pequeños, pero ahora solo empaqueta los resultados de RPC en tipos comunes de medios web.
La verdadera API RESTful parece hipertexto. Cada unidad de información direccionable lleva una dirección, ya sea explícitamente (por ejemplo, atributos de enlace e id) o implícitamente (por ejemplo, obtenida de la definición del tipo de medio y estructura de presentación). Los resultados de la consulta están representados por una lista de enlaces con información resumida, en lugar de matrices de representaciones de objetos (la consulta no reemplaza la identificación de recursos). Las representaciones de recursos se documentan por sí mismas: el cliente no necesita saber si este recurso es un OpenSocialist, porque simplemente afecta las representaciones recibidas.
Piénselo en términos de Internet. ¿Cuántos navegadores web son conscientes de la diferencia entre un recurso de banca en línea y un wiki? Ninguno de ellos No necesitan saber sobre los tipos de recursos. Lo que necesitan saber es posibles transiciones de estado: enlaces y formas, y qué tipo de semántica o acción se entiende al atravesar estos enlaces. El navegador los presenta como controles de interfaz de usuario separados para que el usuario pueda ver posibles transiciones y anticipar el efecto de las acciones seleccionadas. Los bots pueden seguirlos en la medida en que se sepa que las acciones son seguras. Las relaciones mecanografiadas, los tipos de medios específicos y los elementos relacionados con la acción proporcionan la orientación necesaria para los agentes automatizados.
Enlaces utiles:
1.
Versión de traducción de habr.com/us/users/arthuriantech2.
La misma tesis del viejo Roy