Cómo trabajar en la arquitectura, diseño y documentación de la API RESTful

Answer 1

Claro, prueba Visual Paradigm Visual REST API Designer:

Diseñador gráfico API para REST

¿Buscando un diseñador API que ayude? Nuestra herramienta de diseño de API le permite diseñar, describir y documentar RESTful API de manera totalmente gráfica. Puede diseñar RESTful API fácilmente creando un Diagrama de clase simple, como el que se muestra a continuación. El enfoque de diseño gráfico, junto con nuestra galardonada interfaz de diagramación, hacen que el diseño de API sea simple, directo y sin errores.

Generar Swagger / API Blueprint formateado API

Sin escribir una sola línea de código, el diseñador de API puede generar la definición completa de API de acuerdo con la especificación Swagger 2 o API Blueprint. La API detalla todos sus recursos y operaciones basadas totalmente en su diseño visual de API.

Generar documentación de API interactiva.

Genere una hermosa documentación de API interactiva que le permita a su equipo de desarrollo y consumidores finales comenzar fácilmente con sus recursos de API. La documentación visual de la API lo facilita tanto para el desarrollo de back-end como para el consumo del lado del cliente.

Tome un tour bastante:

Conozca más sobre Visual Paradigm REST API Designer

• Descripción general de la generación de API REST
• API REST de modelado
• Generando API REST como proveedor de servicios
• Utilizando la API REST (como consumidor del servicio)

Answer 2

Basado en mi experiencia en el diseño de API REST, lo siguiente es lo que sugeriría

1. Las API, por definición, son interfaces que no deberían cambiar a menudo, por lo que sugerí que pasara días adicionales diseñando antes de que la implementación comience a minimizar los cambios para sus consumidores de API. Esto es especialmente importante si va a enviar una API pública

2. Si está diseñando API REST, asegúrese de poder al menos identificar y congelar los recursos clave en su sistema, incluso si no termina implementando algunos de ellos.

3. Una vez que tenga los recursos, como equipo, intente definir los puntos finales en ellos y dedique un momento a pensar en los parámetros exactos de solicitud y respuesta.

4. Uno de los miembros del equipo puede, en la fase posterior al diseño, comenzar a dedicar tiempo a la documentación. Yo sugerí crear una documentación interactiva como REST API – Software de firma electrónica de documentos – EchoSign porque sirve para ser
a. Un diseño detallado de bajo nivel con cada parámetro pensado y definido cuidadosamente.
segundo. Pruebas a realizar desde la propia documentación.

5. Paralelamente a la documentación, el segundo miembro puede comenzar a implementar la funcionalidad. Si su diseño y documentación se realizan de manera detallada, la implementación debería ser mucho más rápida y limpia

6. El tercer miembro en paralelo puede comenzar a definir casos de prueba y planes de prueba basados ​​en la documentación y las especificaciones / diseño. (S) también puede usar la documentación interactiva para probarlo en vivo

7. Cuando uno de los miembros se libere, pueden ayudarse mutuamente. Si tiene más personas, puede ponerlas en la implementación y la automatización de la API (extremadamente importante para las API)

Puedes leer más sobre las API y el diseño en mi blog El API Blog

Answer 3

Desde mi experiencia y mis lecturas realmente me atengo a los conceptos del libro “RESTful Web Services” de O’Reilly, que es agnóstico en términos de lenguaje incluso cuando hay ejemplos en Ruby.
Además, como arquitecto, hay un concepto que debe seguir siempre, documentar arquitectura es el primero que debe hacer al menos en un nivel básico, es decir, en el momento en que documente ya pasó por el proceso de análisis y las decisiones de diseño arquitectónico sobre la solución. No significa documentar todo, sino al menos documentar los elementos necesarios que reflejen la lógica de su diseño. La documentación debe refinarse más adelante, pero sus decisiones son las primeras en comenzar a trabajar. Así que una vez que lo tengas listo, los pasos (tomados del libro) son (incluyo mis comentarios):
1. Averiguar el conjunto de datos
Debe comprender el conjunto de datos o tener una idea antes de comenzar
2. Divide los datos en recursos.
Los recursos reflejan algo interesante que necesita ser expuesto.
3. Para cada recurso Nombre los recursos con URIs
Autoexplicativo
4. Exponer un subconjunto de la interfaz uniforme.
5. Diseñar la (s) representación (es) aceptada (s) del cliente.
6. Diseñar la (s) representación (es) servida (s) al cliente.
7. Integrar este recurso en los recursos existentes.
8. Considerar el curso típico de eventos.
9. Considere condiciones de error
Ahora añado mi propia perspectiva. Rara vez he visto una API lo suficientemente interesante como para no poder dividirse en muchos programadores. Pero la clave es definir primero el diseño, las reglas, el acceso a los datos, los URI, las prácticas y los patrones. Eso es algo que normalmente puede ser codificado por una o dos personas, después de crear este diseño, hay muchas personas que podrían trabajar en paralelo, por supuesto, se deben considerar dependencias fuertes.
En pocas palabras diría:
1. Comience con la arquitectura (1 arquitecto, Teach Lead, Designer)
2. Comience con el diseño de la API (1 o 2 desarrolladores)
3. Codifique el resto (tantos como pueda dividir el trabajo)

Answer 4

HiBelow se aplica no solo al diseño de la arquitectura de la API Restful, sino también a otras tecnologías.
Digamos que está trabajando con un equipo 3+ y este es un proyecto nuevo. Los siguientes pasos deben resultar en la entrega efectiva del proyecto.

1. El primer paso será analizar los requisitos y dividir los requisitos en historias para crear jiras para cada historia.
2. Por lo general, el líder técnico se involucrará con el equipo de arquitectos técnicos para decidir la tecnología a usar y la arquitectura a seguir.
3. Pase una sesión con desarrolladores y evaluadores que explican la descripción general del proyecto y las historias. Esto les dará una ventaja.
4. El jefe técnico presentará el documento de diseño inicial para que el equipo pueda comenzar su trabajo. Recuerde, el documento de diseño debe ser revisado por el arquitecto.
5. El paso 3 debe realizarse para comenzar con un par de módulos y luego asegurarse de que el documento de diseño para la iteración nth esté listo en la iteración n-1.
6. El paso 4 asegura que una vez que comience el desarrollo, no se detendrá la espera del documento de diseño.
7. Una vez que se realizan los pasos anteriores, se identificarán y entregarán las historias que se entregarán en un sprint, lo que se convertirá en un ciclo.

Sobre posibles problemas:

1. Si el requisito no se analiza correctamente o si existen algunas lagunas en el diseño, se solucionan los problemas.

Poco largo pero responde a la pregunta.

Answer 5

Según mi experiencia, una cosa que puede impedirle hacer esto de manera eficiente sería poner demasiado esfuerzo en la planificación, el diseño y la documentación sin iniciar la implementación. Para evaluar sus decisiones arquitectónicas, algunas veces necesita tener prototipos funcionales. Esto también le proporcionará información temprana sobre qué tan cómodo está su equipo con el uso de nuevas tecnologías o decisiones de diseño.