¿Qué es el campo «contact» en OpenAPI? #
En el ámbito de la creación y documentación de API, OpenAPI se ha convertido en una especificación ampliamente adoptada para definir API RESTful en un formato estandarizado. Esta especificación no solo ayuda en el proceso de desarrollo, sino que también desempeña un papel fundamental para mejorar la capacidad de descubrimiento, la facilidad de uso y el mantenimiento de las API. Entre los diversos campos y componentes de un documento OpenAPI, el campo de contacto (contact) tiene una importancia especial, sobre todo desde el punto de vista del consumidor y del soporte.
Este artículo analiza en profundidad el campo contact: qué es, por qué es esencial y cómo implementarlo correctamente en una especificación OpenAPI.
¿Qué es OpenAPI? #
Antes de entrar en el campo contact, conviene tener una comprensión básica de qué es OpenAPI. La especificación OpenAPI (OAS) es un estándar para definir API RESTful. Ofrece una forma de describir toda la API, incluidos los endpoints, los parámetros de las solicitudes, las respuestas, los métodos de autenticación y otros aspectos esenciales.
Conocida inicialmente como la especificación Swagger, OpenAPI fue adquirida por la Linux Foundation en 2015 y hoy está supervisada por la OpenAPI Initiative (OAI) OpenAPI Initiative. La especificación permite que tanto las personas como las máquinas comprendan las capacidades de un servicio web sin acceso a su código fuente.
Los principales objetivos de OpenAPI son:
- Documentación: generar documentación completa y fácil de mantener.
- Desarrollo: facilitar la creación de API con un enfoque que parte del contrato.
- Pruebas: permitir pruebas automatizadas frente a la API definida.
El campo contact: visión general
#
El campo contact es un elemento opcional de la especificación OpenAPI que sirve para proporcionar información de contacto de quienes mantienen la API. Este campo se encuentra dentro del objeto Info (info), que contiene los metadatos de la API. Este es un ejemplo en formato YAML:
openapi: 3.0.0
info:
title: Sample API
description: This is a sample API
version: 1.0.0
contact:
name: API Support
url: http://www.example.com/support
email: support@example.com
Componentes del campo contact
#
El propio campo contact es un objeto Contact (contact) que puede contener las siguientes propiedades:
- name: el nombre identificativo de la persona u organización de contacto.
- url: la URL que apunta al sitio web de la persona u organización de contacto.
- email: la dirección de correo electrónico de la persona u organización de contacto.
Aunque el campo contact es opcional, rellenarlo puede mejorar de forma notable la usabilidad y la capacidad de soporte de tu API.
¿Por qué es importante el campo contact?
#
Mejora de la confianza de los usuarios #
Cuando los usuarios evalúan si integrarse con una API, suelen buscar señales de fiabilidad y de soporte. Un campo contact bien completado puede generar confianza, ya que asegura a los usuarios que disponen de un medio para pedir ayuda o enviar comentarios.
Facilitar la atención al cliente #
Las API son sistemas complejos, y los desarrolladores que integran tu API pueden encontrar dificultades o problemas. Al incluir información de contacto detallada, les facilitas ponerse en contacto para recibir soporte, lo que puede reducir su frustración y mejorar su experiencia general. Por ejemplo, si se encuentran con un código de respuesta no documentado, saber a quién dirigirse puede ahorrar mucho tiempo y esfuerzo.
Habilitar ciclos de retroalimentación #
Los comentarios de los usuarios son muy valiosos para la mejora continua de tu API. Cuando los desarrolladores saben cómo contactar contigo, pueden aportar ideas y sugerencias valiosas que quizá no habías considerado. Esto, a su vez, puede impulsar un mejor desarrollo del producto y una mayor satisfacción de los usuarios.
Agilizar la comunicación #
En situaciones en las que una API sufre cambios incompatibles o se publican actualizaciones críticas, contar con un punto de contacto te permite difundir la información rápidamente entre tu base de usuarios. Esto puede ser especialmente útil para coordinarse con los desarrolladores durante los ciclos de versionado y obsolescencia.
Cómo implementar el campo contact
#
Buenas prácticas #
- Sé exhaustivo: rellena todas las propiedades disponibles (
name,url,email) del campocontactpara ofrecer varias vías de contacto. - Sé preciso: asegúrate de que los datos proporcionados estén actualizados y se supervisen con regularidad.
- Sé específico: si es posible, indica un contacto específico de la API en lugar de un contacto general de la empresa. Esto ayuda a dirigir las consultas con mayor eficacia.
Ejemplo en YAML #
Este es un ejemplo más completo de un documento OpenAPI con un campo contact:
openapi: 3.0.0
info:
title: Sample API
description: This is a sample API.
termsOfService: http://example.com/terms/
contact:
name: API Support Team
url: http://support.example.com
email: api-support@example.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.1
servers:
- url: https://api.example.com/v1
description: Main (production) server
paths:
/items:
get:
summary: Retrieves a list of items
responses:
'200':
description: A list of items
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
price:
type: number
Ejemplo en JSON #
Este es el mismo ejemplo en formato JSON:
{
"openapi": "3.0.0",
"info": {
"title": "Sample API",
"description": "This is a sample API.",
"termsOfService": "http://example.com/terms/",
"contact": {
"name": "API Support Team",
"url": "http://support.example.com",
"email": "api-support@example.com"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "1.0.1"
},
"servers": [
{
"url": "https://api.example.com/v1",
"description": "Main (production) server"
}
],
"paths": {
"/items": {
"get": {
"summary": "Retrieves a list of items",
"responses": {
"200": {
"description": "A list of items",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"price": {
"type": "number"
}
}
}
}
}
}
}
}
}
}
}
}
Ejemplos del sector #
API de Google #
Google ofrece una amplia documentación y soporte para sus API, incluida información de contacto detallada. Este nivel de detalle garantiza que los desarrolladores dispongan de los recursos necesarios para resolver problemas y obtener más contexto, lo que mejora su experiencia general.
API de Stripe #
La documentación de la API de Stripe es un excelente ejemplo, con puntos de contacto claros para el soporte y recursos adicionales. Esto facilita que los desarrolladores encuentren con rapidez la ayuda que necesitan.
API de GitHub #
De forma similar, la API de GitHub ofrece documentación detallada junto con canales de soporte claros, lo que permite a los desarrolladores desenvolverse con eficacia en la complejidad de la amplia oferta de API de GitHub.
Conclusión #
El campo contact de OpenAPI, aunque opcional, es un punto de contacto fundamental para el soporte a los desarrolladores, los comentarios y la comunicación. Al completar este campo con diligencia, las organizaciones pueden mejorar de forma notable la experiencia del desarrollador, fomentar la confianza y agilizar el proceso de soporte. Como hemos visto, un campo contact bien implementado aporta multitud de beneficios, desde mejorar la confianza de los usuarios hasta facilitar una resolución más rápida de los problemas.
Es un añadido pequeño que puede tener un impacto considerable en la adopción exitosa y la viabilidad a largo plazo de tu API. Por ello, al redactar tu próxima especificación OpenAPI, no pases por alto la importancia del campo contact.
Para obtener más información sobre la especificación OpenAPI, puedes visitar el sitio web oficial de la OpenAPI Initiative.
Última actualización: 21 de mayo de 2024.