Header Ads Widget

Ticker

6/recent/ticker-posts

Por qué debería diseñar API según las especificaciones


Hay una buena razón por la cual la creación de API puede ser extremadamente difícil y requiere mucho tiempo: deben satisfacer las necesidades tanto humanas como de las máquinas .

Inherentemente, esto es bastante difícil. Las máquinas son exigentes y se basan en la lógica pura; anhelan estructuras rígidas y jerárquicas e instrucciones definidas. Por otro lado, los humanos prefieren que las cosas funcionen a un nivel instintivo : nuestro cerebro se las arregla bien para llenar los espacios en blanco.

Las API son la interfaz directa entre la máquina y el desarrollador, por lo que diseñarlas bien significa hacer concesiones. Deben ser lo suficientemente sencillos como para facilitar la serialización y lo suficientemente mínimos como para reducir la sobrecarga innecesaria en cargas útiles. También es útil cuando las API se autodocumentan , con un manejo claro de errores , junto con otras características para maximizar la satisfacción del usuario.

Jason Harmon , director de plataforma de Typeform, sabe cómo hacer estos compromisos. Con su experiencia en la arquitectura de microservicios en PayPal, Braintree y ahora en Typeform, Jason sugiere usar una especificación API como columna vertebral de su proceso de diseño, destacando un enfoque en la usabilidad humana.

Esta publicación se inspiró en una presentación de Jason Harmon. Vea su charla de la Cumbre de la Plataforma de APIs nórdicas 2017 a continuación:

Poniendo las necesidades humanas primero

Satisfacer las necesidades tanto humanas como mecánicas no es fácil, pero Jason está bastante seguro de que los humanos son el mejor punto de partida. La razón es que las máquinas son predecibles y se pueden programar para que funcionen bajo una variedad de restricciones, si se reciben las instrucciones adecuadas. Además, no se tomarán personalmente las negociaciones difíciles de la misma manera que lo harían sus empresarios y desarrolladores.

Pero ... ¿cómo se construye exactamente una API sin poner la máquina en primer lugar?

Jason sugiere que comience escribiendo una breve descripción de su API, describiendo todas las capacidades planificadas en el lenguaje del cliente (que tiene una gran superposición con el lenguaje empresarial). Esto es un poco como el establecimiento de objetivos para su API, y también juega ese papel; La descripción en inglés simple no solo le dirá a la gente de negocios lo que hace la API, sino que también le permitirá a usted (ya todos los demás) decidir si el producto terminado cumple o no con las expectativas.

¿Ahora que? Tenemos una descripción encantadora de nuestra API que aún no se ha creado, pero no responde a ninguna de las preguntas técnicas que hacen los desarrolladores internos y externos.

Jason está seguro de que el siguiente mejor paso es crear una especificación para su API, que puede usar para estructurar y desarrollar su API sin escribir ni una sola línea de código ...

Crear una especificación de API es el siguiente paso natural

En pocas palabras, las especificaciones son documentos que puede utilizar para definir prácticamente todos los aspectos de su API. Se utilizan principalmente para enumerar las muchas funciones y comandos de su API , que puede anotar con descripciones breves, solicitudes o respuestas de muestra, y todos sus parámetros de entrada / salida.

Por lo general, creará especificaciones en un formato estandarizado de su elección, un ejemplo es la muy popular especificación OpenAPI , anteriormente conocida como la especificación Swagger, para servicios RESTful. Es cierto que aquí se vuelve un poco confuso, porque la palabra "especificación" o "especificación" se refiere tanto al documento en sí como al formato que se utiliza.

La especificación OpenAPI es solo uno de los muchos formatos de especificación. Puede leer sobre algunos más populares en nuestro artículo sobre el tema aquí .

Como describe la página de OpenAPI , las especificaciones están diseñadas para " [mapear] de manera efectiva todos los recursos y operaciones asociados con [una API] ". Mejor aún, lo hacen en un formato que es " fácil de aprender, independiente del lenguaje y legible tanto por humanos como por máquinas ". Solo eche un vistazo a este extracto de YAML de la especificación Petstore de OpenAPI:

   delete:
      description: deletes a single pet based on the ID supplied
      operationId: deletePet
      parameters:
        - name: id
          in: path
          description: ID of pet to delete
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '204':
          description: pet deleted
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Es bastante fácil para los humanos y las máquinas comprender que esta parte de la especificación describe una operación llamada deletePet, que, tal como lo dice la clave de descripción, elimina una sola mascota según la identificación proporcionada. También nos dice que el único parámetro de la operación es el de la mascota id(incluso dándonos una breve explicación del parámetro en sí) y muestra las dos posibles respuestas.

Este tipo de notación de objetos debería ser algo familiar para la mayoría de los desarrolladores, por lo que no es ningún problema para ellos elegir OpenAPI y crear una especificación con bastante rapidez.

Ahora, debido a que las especificaciones siguen un formato estandarizado y legible por máquina (o al menos deberían hacerlo, ¡no hay razón para no hacerlo!), Hay cientos, si no miles, de herramientas de código abierto que pueden basarse en las especificaciones que ya ha creado. cosas inteligentes, como crear todo tipo de simulacros y materiales de uso.

Dado que una especificación ya contiene una descripción general clara y completa de todo lo que la API tiene para ofrecer, es fácil empaquetar esta información en, digamos, hermosos documentos de referencia . Puede usar una herramienta como SwaggerUI para eso o, si le gustan los diseños de tres paneles, pruebe ReDoc . Esto no solo ayuda a facilitar el lanzamiento de una API al público, sino que actúa como una prueba inmediata para que la gente de negocios pueda ver resultados tangibles de manera agradable y temprana.

La documentación automatizada es una de las muchas cosas que su especificación puede ayudar a crear. También puede generar stubs de servidor para crear la base para su servidor desde el principio, o crear SDK , como con APIMatic , para distribuir a desarrolladores externos al momento del lanzamiento.

Ahora, si bien su especificación nunca obtendrá datos reales, aún brinda una representación sólida de lo que será capaz de hacer la API terminada y cómo funcionará. Esto significa que desde el principio, puede reclutar a todos los miembros de su equipo, y quizás incluso a unos pocos desarrolladores externos seleccionados, para recopilar comentarios tempranos. Si es necesario realizar algún cambio, ¡entonces es genial que lo haya detectado desde el principio!

Lea también: Uso de un primer diseño de esquema como su única fuente de verdad

Construya solo cuando el diseño basado en especificaciones esté agotado

Con este enfoque de primera especificación para diseñar su API, es posible que se pregunte: ¿ cuándo es realmente el momento de comenzar a construir mi API?

Jason Harman cree que debe dejar de construir la API hasta que haya hecho todo lo posible con solo las especificaciones . Eso significa mapear toda la API, generar todo tipo de simulacros y revisar la especificación hasta que todo el equipo esté satisfecho. Por supuesto, el kilometraje puede variar entre equipos, pero esta es siempre una buena regla general.

Realmente no hay razón para comenzar a construir su API antes de esa fecha; todo lo que terminas es un proceso confuso y bidireccional en el que partes de la API se crean según las especificaciones, y partes de la especificación se crean retrospectivamente para que coincidan con la API.

Por supuesto, podría descartar la especificación a la mitad del proceso de diseño, una vez que esté configurado en cómo debería sentirse la API, pero luego se perderá muchos de los beneficios de usar una especificación en primer lugar, como los documentos automatizados o los SDK instantáneos.

Además, tener una especificación actual sigue resultando útil incluso cuando ya está creando e implementando su API ...

También echa un vistazo a nuestras listas de marcos para la construcción de las API en PHP , Golang , o Node.js .

Consulte siempre las especificaciones

Incluso cuando su API esté completamente redactada, puede seguir volviendo a las especificaciones para obtener más, ¡y debería hacerlo!

Al crear su API, la especificación constituye un punto de referencia ideal para medir si se está moviendo en la dirección correcta y, dado que se puede comprimir en un solo archivo que es tan fácil de distribuir y leer, puede estar seguro de que todos sus los miembros del equipo están en la misma página. Esta es la " única fuente de la verdad " a la que Jason se refiere en su presentación, y facilita la vida de todos.

Al implementar su API, la especificación tiene algunos usos excelentes que a menudo se pasan por alto. Uno de ellos es la validación : puede verificar las solicitudes con el formato en la especificación para evitar escribir la lógica de validación usted mismo, y puede asegurarse de que la API cumpla con los estándares de desarrollo elegidos ejecutándolos sobre la especificación con una herramienta como OpenAPILint .

Ahora, toda esa validación solo es útil si está seguro de que la especificación coincide con la implementación en primer lugar, por lo que sería una tontería no pasar algunas llamadas de API a través de un proxy como Prism para validar la especificación en sí .

También hay enrutamiento . Puede usar su especificación para identificar lo que es interno y externo, o lo que se propone y se publica, durante la implementación para asegurarse de no publicar accidentalmente algo que no debería.

Beneficios de un enfoque de especificación primero

Habiendo leído todo eso, es difícil imaginar la construcción de una API sin una especificación. Los beneficios son infinitos: desde documentos y SDK automatizados hasta una experiencia de diseño mejorada y más inclusiva .

Si disfrutó siguiendo el enfoque de Jason para el desarrollo de API inteligentes, asegúrese de leer la publicación de su blog sobre todas las cosas que Typeform está haciendo para construir la mejor plataforma de desarrollo que pueda.

 

Publicar un comentario

0 Comentarios