Evaluar API de forma rápida y sencilla con OpenAPI

En Nexmo, publicamos especificaciones OpenAPI para todas nuestras API. Esto facilita a los desarrolladores la exploración, evaluación e integración de nuestras APIs en sus propias aplicaciones. Siga leyendo para saber más sobre OpenAPI y por qué compartimos estas especificaciones de API con los desarrolladores.

¿Qué es OpenAPI?

OpenAPI es una forma legible por máquina de describir una API. Está escrita en YAML o JSON y describe el propósito general, el mecanismo de autenticación y otros detalles de la API (si ha oído hablar de Swagger, OpenAPI es su sucesor). También describe en detalle cada uno de los puntos finales de la API. Por ejemplo, aquí tienes un extracto de nuestra API Account, que muestra cómo puedes consultar el saldo de tu cuenta Nexmo:

/account/get-balance:
    servers:
      - url: "https://rest.nexmo.com"
    get:
      operationId: getAccountBalance
      summary: Get Account Balance
      description: Retrieve the current balance of your Nexmo account
      parameters:
        name: api_key
        description: Your Nexmo API key. You can find this in the [dashboard](${CUSTOMER_DASHBOARD_URL})
        in: query
        required: true
        schema:
          type: string
          example: abcd1234
        name: api_secret
        description: Your Nexmo API secret. You can find this in the [dashboard](${CUSTOMER_DASHBOARD_URL})
        in: query
        required: true
        schema:
          type: string
          example: ABCDEFGH01234abc

Como puede ver, el formato de descripción de la API es muy prolijo. Esto se debe a que necesita describir una API tan bien que incluso las máquinas puedan entenderla. El ejemplo que se muestra aquí contiene la URL, el verbo y los parámetros necesarios para obtener información sobre el saldo de la Account. La especificación también proporciona una forma de describir los estados de las respuestas y las cargas útiles que pueden devolverse, ¡tanto las satisfactorias como las de otro tipo!

Descargar una especificación OpenAPI

Las especificaciones OpenAPI se utilizan ampliamente en las empresas proveedoras de API. Las especificaciones legibles por máquina pueden ser muy potentes en el ciclo de desarrollo, ya que permiten la generación automatizada de código, pruebas y SDK de bibliotecas.

Sin embargo, la especificación OpenAPI resulta aún más útil cuando se comparte ampliamente fuera de la propia organización del proveedor de la API. Es un buen indicador de las prácticas modernas de las API, y es mucho más rápido obtener un archivo de formato estándar para utilizarlo en tus propias herramientas que buscar información en documentación desconocida. Estamos viendo que muchos proveedores de API ofrecen especificaciones OpenAPI para sus API, y nos encanta :)

Si consulta una página de referencia de la API Nexmo, verá un botón como éste:

A big blue Download OpenAPI 3 Description button

La documentación de referencia de la API se genera a partir de la propia especificación OpenAPI, y haciendo clic en el botón de descarga obtendrá el archivo YAML de origen. También puede encontrar todas nuestras especificaciones en GitHub.

Explorar la API en Postman

Lo que más nos gusta hacer con un archivo OpenAPI que no hemos visto antes es importarlo a Postman. Si aún no estás familiarizado con esta excelente herramienta, es un cliente HTTP realmente bueno que es muy valioso cuando se trabaja con APIs (en realidad es mucho más que eso, compruébalo por ti mismo).

Postman ahora soporta ficheros OpenAPI v3. Puede importar un archivo al crear una colección:

Shows the import dialog when creating a collection

La importación de una especificación OpenAPI producirá una "Colección" de solicitudes de API ya preparada, y cada punto final individual ya tiene una solicitud creada para usted. Puede añadir rápidamente su clave de API, el secreto y cualquier otro parámetro necesario para esta solicitud y ejecutarla.

check balance postman

Me parece una forma muy rápida de explorar una API con la que no estoy familiarizado. En lugar de tener que leer los documentos y reconstruir algunas llamadas a la API de ejemplo para tratar de averiguar si esta API en particular satisfará mis necesidades, todo está delante de mí.

Pro-Tip: siéntase libre de probar esto ahora con la API Nexmo. Necesita crear una Account primero, pero no te preocupes, viene con un poco de crédito gratis para que juegues.

Genere su propio SDK

En Nexmo publicamos SDK de servidor en seis pilas y media de tecnologías diferentes, pero no todos los proveedores de API lo hacen, o puede que no ofrezcan el lenguaje de programación que estabas buscando. Como solución intermedia entre un SDK decente y nada en absoluto, puede utilizar un generador de código para crear una envoltura básica para la API. Consulte la sección "Generadores de SDK" en https://openapi.tools/#sdk para ver algunos ejemplos.

Disponer del SDK "real" o de uno generado puede acelerar bastante las integraciones de API; las funciones de autocompletado en tu IDE son mucho más rápidas que buscar cosas en la documentación a cada paso. Generar un SDK sólo para una parte de la API también puede conducir a menos dependencias o a una base de código más pequeña y, en algunas situaciones, eso es realmente importante. Elegir un proveedor de API que te proporcione la especificación OpenAPI es muy útil en esos casos.

Nota del editor: Más información sobre OpenAPI

Si está interesado en saber más sobre OpenAPI, venga a nuestro evento del evento Vonage Campus en San Francisco? Lorna (la autora de este post) estará allí para dar una charla sobre OpenAPI - y le encanta charlar sobre OpenAPI en general, así que es una gran oportunidad para pasar el rato con la gente de Nexmo y hablar de APIs.