Estructuración de la documentación en línea para una API REST

85

Estoy construyendo mi primera API Rest que serializa datos en formatos JSON y XML. Me gustaría proporcionar una página de índice a los clientes de API, donde podrían elegir los puntos finales implementados.

¿Qué información debo incluir para que mi API sea más útil y cómo debo organizarla?

api rest indexing aumanets
fuente

Respuestas:

6

Esa es una pregunta muy compleja para una respuesta simple.

Es posible que desee echar un vistazo a los marcos de API existentes, como Swagger Specification ( OpenAPI ), y servicios como apiary.io y apiblueprint.org .

Además, aquí hay un ejemplo de la misma API REST descrita, organizada e incluso diseñada de tres formas diferentes. Puede ser un buen comienzo para que aprenda de las formas comunes existentes.

En el nivel más alto, creo que los documentos de API REST de calidad requieren al menos lo siguiente:

  • una lista de todos los puntos finales de su API (URL base / relativas)
  • tipo de método HTTP GET / POST / ... correspondiente para cada punto final
  • solicitud / respuesta tipo MIME (cómo codificar parámetros y analizar respuestas)
  • una solicitud / respuesta de muestra, incluidos los encabezados HTTP
  • tipo y formato especificados para todos los parámetros, incluidos los de la URL, el cuerpo y los encabezados
  • una breve descripción de texto y notas importantes
  • un fragmento de código corto que muestra el uso del punto final en lenguajes de programación web populares

También hay muchos marcos de documentos basados ​​en JSON / XML que pueden analizar la definición o el esquema de su API y generar un conjunto conveniente de documentos para usted. Pero la elección de un sistema de generación de documentos depende de su proyecto, idioma, entorno de desarrollo y muchas otras cosas.

Igor Kroitor
fuente