¿Debo describir los servicios REST en un formato legible por máquina?

Question

La mayoría de las interfaces REST que veo se describen con una página web simple que describe la URL, el método, la entrada aceptada y el resultado devuelto. Por ejemplo, la documentación Amazon S3 o Twitter API.

Pero ¿por qué debería conformarme con lo que aparentemente es lo suficientemente bueno para Amazon o Twitter ... Entonces, ¿vale la pena describir una API REST en un formato legible por máquina? Y si es así, ¿cuál?

WSDL 2.0 reclamaciones es capable of describing REST. WADL se creó explícitamente para describir servicios REST. Tanto WSDL 2.0 como WADL parecen tener un cajero automático más bien pequeño y parece ser de poco rendimiento por el esfuerzo de crear y mantener los documentos de descripción. Mi pregunta es básicamente validar o negar mi suposición.

¿Utiliza WSDL/WADL para describir sus servicios? ¿Confía en WSDL/WADL para consumir los servicios de otros? ¿Su herramienta de elección es compatible con cualquiera de estos en este momento?

Answer 1

El siguiente es sólo mi opinión personal:

creo WADL es similar a mapas de sitio para las páginas HTML. Los mapas de sitio se consideran teóricamente una buena práctica, pero raramente implementados y aún más raramente utilizados por las personas.

Creo que la razón es simple: deambular por un sitio y presionar los botones colocados estratégicamente a menudo es mucho más gratificante que navegar por un mapa complejo.

REST Los métodos API no deberían requerir una descripción formal. Por lo tanto, si la API se crea cuidadosamente, es bastante fácil descubrir todos los recursos simplemente siguiendo los enlaces uri estratégicamente ubicados de un recurso RESTful "doméstico".

Answer 2

¿Cuál es el beneficio de una definición de API REST legible por máquina?

El objetivo de REST es que la API sea relativamente simple y fácil de entender. El lenguaje natural funciona bien para esto.

Si quiere decir "Definiciones de tipos de API" cuando dice "Definición de API", puede que haya algún valor al proporcionar metadatos. Esto, sin embargo, es solo una parte de una definición de API.

Tener API "legible por máquina" puede repetir fácilmente el código fuente API, violando el principio DRY.

A menudo es más simple escribir descripciones en inglés de lo que hacen los verbos REST y cuáles son los URI. Envíe los tipos que se organizan a través de JSON (o YAML o JAXB) como código fuente. Esa es la API legible por máquina perfecta: fuente real de trabajo para la clase de objeto de mensaje.

Answer 3

Hay un phenonenon de pollo/huevo aquí. WADL es inútil sin herramientas que lo produzcan o consuman. Las herramientas son inútiles a menos que los sitios publiquen WADL. etc.

Para mí, el modelo de Amazon funciona bien. Dependiendo de su público, obtendrá un mayor rendimiento en un esfuerzo para producir muestras, incluidos los diálogos de ejemplo de od snip (qué aspecto tiene request1 en el cable, lo mismo para la respuesta 1, luego request 2, response 2, etc.) y el código en vario idiomas que son importantes para ti. Si desea ir a una definición legible por máquina, puede usar XSD si es un formato de mensaje XML. Obviamente, esto no es WADL sino que, junto con su descripción en inglés, puede proporcionar una pequeña utilidad adicional para los desarrolladores.

Answer 4

Sí, deberías.Podrá generar su código de cliente, pruebas y documentación utilizando un conjunto de herramientas que soportan WADL. Se pueden encontrar algunos ejemplos here. Además, creo que debería quedarse con WADL, en lugar de WSDL 2.0 porque es menos detallado y mucho más simple (en mi humilde opinión). De hecho, en WADL usted describe exactamente lo que el usuario ve en la página de documentación, simplemente usando la sintaxis WADL XML. Por cierto, es por eso que es tan fácil escribir generadores de documentación basados ​​en XSLT para WADL.

Answer 5

El uso más popular de WSDL (y WADL de la misma manera) es la generación de código. Sin duda, ayuda a acelerar el desarrollo, pero nada puede reemplazar la antigua documentación simple. Para los humanos y no para las máquinas.