Header Ads Widget

Ticker

6/recent/ticker-posts

Desarrollo de API de descripción agnóstica con API Transformer

 

APi-transformador-01

Si bien muchos aspectos de la economía de las API están sujetos a discusión y conjeturas, si hay una verdad es esta: cuando se trata de describir con éxito su API, el jurado está deliberando sobre la mejor herramienta para el trabajo. A medida que la economía de las API ha crecido, también lo ha hecho el número de especificaciones de descripción de API, cada una con su propio formato específico y herramientas de apoyo. El hecho de que Swagger haya sido elegido por la Fundación Linux para ser el estándar formativo para la Iniciativa de API Abierta podría indicar que Swagger se volverá aún más frecuente, pero dada la inversión de las organizaciones en una elección de especificación particular, es poco probable que haya un enfoque homogéneo. adoptada en toda la industria en el corto plazo.

Junto con esta dialéctica, la creciente popularidad del enfoque de diseño de API primero hace que las especificaciones de descripción de API sean más fundamentales para el proceso de desarrollo. Las especificaciones de API se están convirtiendo en el producto del diseño, generadas por herramientas de creación de prototipos como RAML Designer, API Blueprint, Readme.io o Swagger Editor, con la documentación y una maqueta disponibles antes de que el desarrollador comience a codificar. Esta es una desviación del método de descripción retrospectivo que generalmente ha prevalecido hasta hace poco, donde el desarrollador anota el código o produce manualmente una representación esquemática de la API para transmitir su diseño. Por el contrario, el diseño de API primero se esfuerza por optimizar la API expresamente para sus propios objetivos, ignorando intencionalmente las limitaciones de la organización, arquitecturas y convenciones programáticas para crear una definición de API que cumpla exactamente con la intención y los requisitos de diseño. Sin embargo, el principio de diseño de API primero también puede resultar en un bloqueo tecnológico para los equipos de desarrollo, vinculando a los desarrolladores a un conjunto dado de herramientas y lenguajes de programación que admiten el formato de especificación elegido.

Dónde encaja el transformador API

La evolución del proceso de diseño y desarrollo de API es una de las razones por las que API Transformer, creado por APIMATIC, es un desarrollo interesante. API Transformer proporciona una herramienta, el "Convertron", que facilita a los desarrolladores la conversión de un formato de especificación de API a otro, y admite la mayoría de las especificaciones de API populares, incluidas las principales versiones de Swagger, RAML y WADL. API Transformer proporciona una interfaz de usuario web que un desarrollador puede usar para convertir una especificación existente a un formato alternativo simplemente completando los campos obligatorios:

Transformador de API - Página de inicio

Sin embargo, el verdadero poder de Convertron es que también proporciona una API simple, que proporciona la misma funcionalidad que la interfaz de usuario de una manera que se puede utilizar mediante programación. El siguiente ejemplo es un comando cURL que convierte una especificación Swagger 2.0, el ejemplo de la tienda de mascotas proporcionada por Swagger a RAML:

curl -o petstore.raml -d 'url=https://raw.githubusercontent.com/swagger-api/swagger-spec/master/examples/v2.0/json/petstore.json' https://apitransformer.com/api/transform?output=raml

Esta funcionalidad hace posibles varios casos de uso interesantes:

  • Permite a los desarrolladores elegir la especificación de API que tenga más sentido para ellos o que pueda consumir con sus herramientas de desarrollo favoritas, lo que significa que los equipos de diseño y desarrollo tienen mayor flexibilidad;
  • Un proveedor de API también puede ofrecer especificaciones de API para descargar desde su portal de desarrolladores en una variedad de formatos, que pueden ser útiles para la comunidad de desarrolladores y aumentar la participación al comunicarse con ellos de una manera que entiendan;
  • Un proveedor de API puede extender la cobertura de sus pruebas, probando con formatos generados para garantizar que haya pocas diferencias semánticas entre un formato y otro, proporcionando una mayor resiliencia en el proceso de desarrollo;
  • Por último, los proveedores de API también pueden migrar fácilmente de las especificaciones descriptivas "heredadas" a otras con mejor soporte, por ejemplo, WADL.
Tutorial: Creación de un bot inteligente con la API de Slack

Ejemplo de caso de uso

Para probar los casos de uso anteriores, tomamos el concepto de un portal para desarrolladores donde se usa API Transformer para crear traducciones de una descripción de API. El proveedor de API que es propietario del portal de desarrolladores en este caso de uso especifica sus API utilizando Swagger y publica la especificación en diferentes formatos como una conveniencia para la comunidad de desarrolladores. En este escenario, imaginamos que se trataba de una faceta del proceso de desarrollo, incrustado en la integración continua: cuando el código se publica en el repositorio de git para la API, se ejecuta un proceso que crea traducciones de la descripción de Swagger en varios formatos predefinidos. Los pasos del proceso son:

  • Los desarrolladores envían cambios de código al repositorio de git para la API;
  • El servidor de CI detecta la confirmación y activa una instancia de la API, verificando si el Swagger JSON ha cambiado;
  • Si se detecta un cambio, se ejecuta un conjunto de pruebas de estilo Gherkin contra la API;
  • Al completar con éxito el conjunto de pruebas, se genera una versión de la especificación en los formatos alternativos que el proveedor de API pone a disposición. Esto está preparado para ser insertado en un CDN para poblar el portal.

Para demostrar esto, hemos creado un prototipo funcional en Python y Jenkins, la configuración está disponible en GitHub . En primer lugar, creamos una API muy simple usando Flask-RESTPlus, describiendo la API usando el azúcar sintáctico basado en Swagger que ofrece Flask-RESTPlus:

from flask import Flask
from flask.ext.restplus import Api, Resource, fields
from uuid import uuid4

app = Flask(__name__)
api = Api(app,
          version="1.0",
          title="API Transformer demonstration",
          description="API created to demonstrate the functionality offered by the API Transformer Convertron")
demo_ns = api.namespace('demo', description='Demo operations')


@demo_ns.route('')
class Demo(Resource):
    @api.doc(description='A demo HTTP GET',
             responses={400: ("Bad request", api.model('Error', {"message": fields.String})),
                        500: "Unhandled exception (captured in server logs)"})
    def get(self):
        return 'This is a demo!', 200

    @api.expect(api.model('Demo Request', {"data": fields.String(required=True)}))
    @api.doc(description='A demo HTTP POST',
             responses={400: ("Bad request", api.model('Error', {"message": fields.String})),
                        500: "Unhandled exception (captured in server logs)"})
    @api.marshal_with(api.model(
        'Demo Response',
        {"id": fields.String(required=True), "data": fields.String(required=True)}), code=201)
    def post(self):
        return {'id': uuid4().hex, 'data': 'Created new demo resource'}, 201

if __name__ == '__main__':
    app.run(port=8080, debug=True)

Descarga nuestra guía de desarrollo gratuita

En aras de la brevedad, creamos un trabajo simple que se activaba cuando se realizaba una confirmación en un repositorio de git local (en realidad, obviamente, agregaríamos el conjunto de pruebas y verificaríamos los cambios de contenido para cada nueva versión). Cuando se activa, se ejecuta un paso de compilación del script de shell que inicializa una instancia de nuestra API de demostración, descarga una copia de Swagger JSON y luego recorre nuestros tipos de formato alternativo de destino:

# Loop through formats and transform
for format in raml "api%20blueprint" "apimatic" ; do
    ext=$(echo $format|tr " " "_")

    # Curl for each target format
    echo "info: Generating spec for ${format}"
    curl -X POST "https://apitransformer.com/api/transform?output=$format" \
    -o $WORKSPACE/transformer_output/app.${ext} -H "Content-Type: text/plain" -d @$WORKSPACE/swagger.json

    if [[ $? -ne 0 ]] ; then echo "error: Failed to generate spec" && exit -1; fi

done

Tras una ejecución exitosa, se generan nuevas traducciones de la especificación Swagger en formatos RAML, APIMATIC y API Blueprint y se guardan en el espacio de trabajo del trabajo. Las nuevas versiones de la especificación se envían a un depósito de S3 (mediante el complemento S3 , listo para ser referenciado por una distribución de CloudFront.

Transformador API - Bucket S3

Conclusión: el valor de API Transformer

transformador

No hay duda de que API Transformer ofrece una perspectiva útil para los diseñadores y desarrolladores de API para ayudarlos a convertir rápidamente una API de una especificación de descripción a otra. La debida diligencia y las pruebas adicionales por parte de la comunidad de desarrolladores determinarán si existen diferencias semánticas entre las especificaciones de origen y cualquiera de los objetivos que genera API Transformer, y esto demostrará su valor como herramienta para la comunidad de API.

Continuaremos usando y revisando API Transformer y ofreceremos más información sobre él y herramientas comparables que se introducen en el mercado.

Publicar un comentario

0 Comentarios