Introducción a Apiary y como crear APIs
La Interfaz de Programación de Aplicaciones (API) tiene operaciones que pueden ser consumidas por la aplicación. Comprendamos con la ayuda de un escenario donde las API desempeñan un papel. Supongamos que hay una compañía de taxis que desea permitir la reserva de un taxi a través de una aplicación móvil o un sitio web. Ahora, esta característica u operación debe estar expuesta para que pueda ser utilizada por los clientes que están desarrollando los sitios web o una aplicación móvil. La operación para exponer la reserva de la cabina tendrá algunos parámetros de entrada y salida. Estas operaciones son un contrato entre las personas que crean la API y las personas que consumen la API. En este artículo, veremos cómo Apiary juega un papel en el diseño de API, haremos una introducción a Apiary y como crear APIs con esta plataforma adquirida por Oracle recientemente
Aquí, veremos cómo Apiary puede ayudar a diseñar API rápidamente y cómo puede ayudar a superar algunos problemas comunes de implementación e integración.
¿Qué es Apiary?
Apiary nos permite primero crear el diseño de una API y luego implementarlo. Apiary ayuda a crear un marco simulado del API y también genera su documentación con bastante rapidez. En el diseño del API, especificamos las operaciones compatibles, los parámetros de entrada para las operaciones y también el modelo de datos de salida; en otras palabras, salida JSON. Estas APIs simuladas se pueden consumir en las aplicaciones para ver si el diseño de la API cumple con las necesidades de la aplicación. Con Apiary, las modificaciones se pueden modificar rápidamente y pueden pasar por varias iteraciones muy rápidamente sin escribir ningún código.
¿Por qué Apiary?
Generalmente, si deseamos crear una API, primero definimos el esquema para la entrada y la salida. Luego, definimos las operaciones para devolver los datos; en otras palabras, implementamos una solución mínima antes de que pueda integrarse.
Con Apiary, las API se pueden diseñar (o declarar) donde se pueden burlar los datos de entrada y de salida. Los datos simulados representan el resultado que devolverá la acción. Esta API simulada y los datos se pueden integrar y probar para verificar que cumplan con los requisitos de la aplicación. Estos cambios pueden realizarse sin ningún esfuerzo de codificación.
Esto también ayuda cuando hay varios equipos trabajando simultáneamente. Un equipo trabaja en la implementación de API y otros equipos consumen las API. Una vez que se finaliza el contrato, ambos equipos pueden trabajar de forma independiente.
Como Usar Apiary
Para usar Apiary para diseñar API, haga clic en ‘Apiary’. Use su cuenta de GitHub para iniciar el diseño de la API. Una vez iniciada la sesión, la UI ofrece una opción para crear una nueva API. Especifique un nombre y haga clic en el botón «Crear API». Crea los métodos API simulados; por ejemplo, enumerar notas, crear notas, recuperar un nodo por ID, etc. También especifica los diferentes métodos HTTP que se utilizan; en otras palabras, GET, POST, DELETE, y así sucesivamente.
Comprendamos las diferentes secciones de la declaración API.
1. FORMAT: 2A
2. # testAPI
3. Notes API is a *short texts saving* service similar
to its physical paper presence on your table.
4. # Group Notes
5. Notes related resources of the **Notes API**
6. ## Notes Collection [/notes]
7. ### List all Notes [GET]
8. + Response 200 (application/json)
9. [{
10. "id": 1, "title": "Jogging in park"
11. }, {
12. "id": 2, "title":
"Pick-up posters from post-office"
13. }]
Una API de ejemplo se declaró en el fragmento de código anterior, y la salida de la documentación de esta se muestra en la Figura 1.
- Linea 1: FORMAT specifies the version of the API.
- Linea 2: En #testAPI, ‘#’ define el encabezado en la documentación. El número de símbolos # define los subtítulos; en otras palabras, ## & ### en la línea 6 y 7 define los subtítulos.
- Linea 4: # Group Notes define un grupo llamado ‘Notes’.
- Linea 6: define el subtítulo y la URL para acceder a la API.
- Linea 7: especifica el método HTTP y el nombre de la acción. En este caso, el método HTTP es ‘GET’ y el nombre de la acción es’Notes’.
- Linea 8: especifica que la acción devuelve un código de estado de respuesta como 200 y los datos JSON.
Esto explica cómo las API simuladas devuelven datos. La pantalla en la Figura 1 muestra la documentación creada para el diseño de la API.
También es compatible con otros verbos como ‘POST’ y ‘DELETE’. Un ejemplo para el ‘POST’ es:
1. ### Create a Note [POST]
2. + Request (application/json)
3. { "title": "Buy cheese and bread for
breakfast." }
4. + Response 201 (application/json)
5. { "id": 3, "title": "Buy cheese and
bread for breakfast." }
En la línea 1, se define el método HTTP «POST». En este ejemplo, toma un parámetro de solicitud llamado ‘title’ y devuelve un código de respuesta 201 y datos JSON compuestos de id y títle.
Resumen
Con Apiary, el enfoque de «design API first» puede implementarse donde los parámetros de entrada/salida se pueden finalizar y las maquetas se pueden probar incluso antes de que se implemente. Esto mejorará la coordinación entre los equipos y también la productividad.
