38 votos

Los métodos estándar para la documentación de una API RESTful

Estoy escribiendo una especificación para una API RESTful para un nuevo interna del servicio web. No es muy largo y bastante sencillo, pero aun así, es mi primera vez usando el REPOSO estricto (como opuesto a la trampa por razones prácticas, evitando PUT y DELETE porque son un dolor en PHP, y así sucesivamente). Me preguntaba si había alguno de los métodos estándar o las mejores prácticas para documentar una interfaz REST? Quiero que el resto del equipo para entender de un vistazo, y para cualquier persona que quiere escribir un cliente para ser capaz de hacerlo sin entender el código subyacente.

23voto

turtlemonvh Puntos 632

Seguro, las Api de REST ideal es que debe utilizar HATEOAS y ser hipertexto impulsado (con el uso intensivo de los tipos de medios), pero también teniendo simple amistoso humanos de la documentación para los desarrolladores para trabajar es útil.

Algunas herramientas específicas que son útiles para la generación de documentación como este:

  • Swagger
    • Abierto de especificaciones para la descripción de la Api de REST [ github ]
    • Herramientas para la auto-generación
      • Documentación
      • Código de la API
  • Mashery
    • Un proyecto de código abierto [ github ]
    • Herramientas para la generación de
      • Documentación
      • Una exploración de la interfaz de la API
  • Colmenar y de la API de Blueprint
    • Escribir la descripción de la API de en un DSL dentro de rebajas
    • Herramientas para la auto-generación
      • Documentación
      • Simulacro de servidor
    • Parece estar centrado en ruby+mac devs
  • RAML
    • Una especificación para describir las Api de REST [ github ]
  • WADL
  • APIgee
    • Un producto comercial con algunas características de la documentación
  • 3scale
    • Un producto comercial con algunas características de la documentación

12voto

Martin Konecny Puntos 7328

He estado usando http://apiary.io, que es bastante agradable. También puede exportar la documentación de la API de github.

6voto

Darrel Miller Puntos 56797

Roy el post de aquí que los estados

Una API REST debe pasar casi todos los de sus descriptivo esfuerzo en la definición de la tipo de medio(s) que se utiliza para representar los recursos y la conducción de la aplicación estado, o en la definición ampliada relación de nombres y/o hipertexto habilitado mark-up existentes estándar de tipos de medios. Cualquier esfuerzo invertido describir qué métodos usar en lo que Uri de interés debe ser totalmente definido en el ámbito de la las reglas de procesamiento para un tipo de medio (y, en la mayoría de los casos, ya definidas en los actuales tipos de medios).

4voto

serialseb Puntos 5509

Un buen Resto de documentación significaría que la documentación de su tipo de medios y único de su tipo de medios.

En un escenario típico, tendría que producir un documento así:

El Acme Corp formatos xml

Enlace descubrimiento Enlaces a varios recursos se describen en un documento que se puede encontrar mediante la emisión de una solicitud GET o HEAD al servidor en un marcador URI (normalmente la raíz del servidor, http://www.acme.org), y en busca de un Vínculo HTTP encabezado.

Link: ;rel="http://rel.acme.org/services";type=application/vnd.acme.servicios+xml

donde el rel parte es el vínculo de la relación, y xxx es el identificador URI para que la relación ha sido establecida.

Relaciones de vínculo Este documento define la siguiente relación de los nombres de: http://rel.acme.org/services El vínculo de relación se describe la lista de enlaces que pueden ser navegado. http://rel.acme.org/customers El enlace para el que esta relación se utiliza es la lista de clientes.

Tipos De Medios El application/vnd.acme.servicios+xml es un documento con una serialización xml que describe una lista de los enlaces de una aplicación desea, puede procesar.



La aplicación/vnd.acme.clientes+xml es un documento con una serialización xml que describe a los clientes.

Ejemplo doucments:



etc...

El punto es dar una forma a la que el desarrollador siga los enlaces de definir. En primer lugar, encontrar el enlace al índice para que puedan obtener la lista de cosas de las que puede navegar.

Una vez que descubren que doucment, descubren que se puede ver una lista de clientes en un determinado uri, y puede hacer un GET en contra de ella.

Si se encuentran con un cliente de su interés, puede seguir el enlace definido en /clientes/cliente/@href y emitir un GET para recuperar un represtnation de ese cliente.

A partir de allí, su tipo de medios podría incrustar acciones que están disponibles para el usuario, utilizando más enlaces. Usted también tiene la opción adicional de la emisión de una solicitud de OPCIONES en el recurso para saber si se puede permitir la eliminación del recurso, o un PUT si usted puede guardar el documento de nuevo después de la modificación.

Así que un buen doucmentation no siempre:

  • dar link
  • dar de interacción tales como "usted puede emitir POST de los Clientes con este tipo de medios y que significa que la operación de mover". El cliente debe emitir un POST en contra de Custoemr sólo porque su xml doucment ha especificado de esa manera.

El punto de todo esto es lograr la máxima acoplamiento flexible entre el cliente y el servidor. El cliente puede ser muy inteligente en la visualización y idscovering recursos (mostrando formas y dios sabe qué más), pero es totalmente tonto como para lo que el actual flujo de trabajo es: el servidor decide.

3voto

Avi Flax Puntos 14898

En mi empresa, hemos sido muy felices usando WADL, una Aplicación Web Lenguaje de Descripción. Wikipedia describe como: "un lenguaje basado en XML formato de archivo que proporciona legible por una máquina, descripción de HTTP basada en aplicaciones web". Me parece raw WADL fácil escribir, leer y comprender, y se asigna directamente a RESTful conceptos. El proyecto oficial proporciona una simple especificación, XSD y RELAX NG esquemas y herramientas Java.

Un número de herramientas y recursos que existen para trabajar con WADL, incluyendo:

  • wadl_stylesheets, hojas de estilos XSLT para crear HTML de la documentación de archivos WADL
  • Restlet, un marco de Java para la construcción de Descanso de los servidores y de los clientes, incluye una extensión WADL

Un consejo: intentar incluyendo la documentación legible, tales como descripciones, conceptos, primeros pasos, consejos de uso, etc, en el WADL del documento doc elemento mediante la inclusión de elementos HTML, utilizando el XHTML espacio de nombres. Se puede hacer una gran diferencia!

Iteramos.com

Iteramos es una comunidad de desarrolladores que busca expandir el conocimiento de la programación mas allá del inglés.
Tenemos una gran cantidad de contenido, y también puedes hacer tus propias preguntas o resolver las de los demás.

Powered by: