issues - Documentación API RESTful
jira software rest api (4)
Voy a diseñar pronto una API RESTful, por lo que debo describirla para permitir que otras personas comiencen a implementar clientes que la usen.
Miré un poco, pero desafortunadamente no encontré ninguna forma estandarizada de describir los servicios RESTful basados en la web. Lo que estoy buscando es algo así como JavaDoc, aunque no tiene que generarse a partir de ningún tipo de código. Tampoco estoy hablando de algo como WADL, prefiero tener alguna documentación legible por humanos que pueda distribuir.
Debido a la naturaleza de los servicios RESTful basados en la web, debería ser bastante fácil estandarizar una documentación. Solo debe enumerar los recursos disponibles, los URI correspondientes, los métodos permitidos, los tipos de contenido y describir las acciones disponibles. ¿Tienes alguna sugerencia por lo tanto?
Gracias de antemano y saludos
Debido a la naturaleza de los servicios RESTful basados en la web, debería ser bastante fácil estandarizar una documentación. Solo debe enumerar los recursos disponibles, los URI correspondientes, los métodos permitidos, los tipos de contenido y describir las acciones disponibles. ¿Tienes alguna sugerencia por lo tanto?
Esta es una manera absolutamente incorrecta de documentar los servicios REST.
Un URI para gobernarlos a todos
Nunca debe enumerar los URI de los recursos porque eso animaría a un cliente a codificar esos URI en el código del cliente. Esto crea un acoplamiento innecesario entre el cliente y el servidor. Los URI deben descubrirse al navegar desde el URI de raíz de servicios. El URI raíz es el único URI que debe documentarse. La documentación debe centrarse en describir qué información y enlaces se encuentran en las representaciones que se devuelven. Si comienza con la representación que se devuelve desde el URI raíz, puede describir el tipo de medio y cuáles son los enlaces que se pueden proporcionar en ese documento.
Alias tus URI
Es importante usar algún tipo de alias para crear una capa de indirección entre el cliente y el servidor. Si sigue el estándar átomo: enlace para definir enlaces, entonces el atributo rel se convierte en el identificador. Sin embargo, hay otras formas de definir enlaces, como, por ejemplo, la forma en que se incrustan las imágenes en html. Una etiqueta de imagen puede tener un Id y un href. La etiqueta Id debe usarse para identificar la imagen a la que desea acceder.
Los tipos de medios definen tu API
El resultado final es que define todos los puntos finales en su API dentro del contexto de alguna representación. La API completa se define por el conjunto de representaciones devueltas y los enlaces que las conectan.
Entonces puedes preguntar, ¿cuál es la diferencia? ¿Por qué no simplemente crear la lista de puntos finales? Aquí hay algunas razones,
Espacio de URI cambiante
Debido a que el cliente accede a estos enlaces mediante un alias, esto permite que toda la estructura de URL de su sitio sea completamente modificable sin afectar al cliente. Esto hace que todas las interminables preguntas sobre "cuál es la mejor forma de estructurar mi URL jerárquica" sean prácticamente irrelevantes. Puedes intentarlo de una manera, y si no funciona, simplemente cámbialo, ¡no romperás ningún código de cliente ni tendrás que cambiar ninguna documentación!
Distribución dinámica
No es solo la parte de la ruta del URI que puede cambiar. También puedes cambiar el host. Imagine que su aplicación está empezando a obtener un uso mucho mayor de lo esperado, puede cambiar fácilmente el host de todos los recursos de imagen o video para apuntar a un servidor diferente. Incluso podría proporcionar un equilibrio de carga simple al devolver diferentes hosts. Como las API RESTful son apátridas, realmente no importa qué servidor responde a la solicitud. Esta función es útil para muchos escenarios: mover cosas HTTPS en un servidor dedicado, distribuir geográficamente solicitudes basadas en la ubicación del cliente, particionar verticalmente las funciones de la aplicación en diferentes servidores.
Protocolo explícito
Solo porque una representación puede devolver un enlace, no significa que siempre lo hará. El servidor solo puede devolver los enlaces que están permitidos en función del estado del recurso actual. Esto puede ser realmente útil cuando hay un protocolo específico que se debe seguir al interactuar con un recurso de servidor. El código del cliente no necesita comprender las reglas del protocolo, solo puede presentar al usuario los enlaces que el servidor ha puesto a su disposición.
No puedes autogenar las cosas interesantes
La razón por la cual la mayoría de los esfuerzos automatizados para documentar los servicios REST no son efectivos es porque la interfaz uniforme elimina la necesidad de documentar lo fácil. Una vez que entiendes HTTP (ver RFC2616), entiendes todos los mecanismos de la API. Todo lo que queda es la información específica del dominio realmente interesante que no se puede generar.
Mira el lado positivo, la documentación debería ser mucho más corta. Cualquier tiempo extra disponible debe dedicarse a proporcionar ejemplos de cómo navegar por la API para escenarios comunes.
No hay un estándar, solo un debate abierto. Hay un artículo interesante en InfoQ: Describir aplicaciones RESTful .
Si está utilizando el patrón MVC, la URL generalmente se representa como:
example.com/class/function/ID
Estas son piezas de información accesibles pragmáticas, lo que significa que aún podría usar JavaDoc y documentar el enfoque RESTful, ya que cada parte de la URL está conectada al código fuente en sí.
Si usa algo como JAX-RS , puede usar el JavaDoc real de la implementación como referencia. O hacer análisis de anotaciones y generarlo automáticamente tampoco debería ser demasiado difícil, aunque no conozco una implementación específica.