Diseño de API

Cómo pasar de unos requisitos a una API

Como en la mayoría de las tecnologías, una API es una solución a un problema. Para diseñar la API correcta, debe asegurarse de que el problema que esté abordando esté claramente definido respondiendo a las siguientes preguntas:

• ¿Quiénes son los consumidores o público destino de esta API?
• ¿Qué tipo de información manipularán los consumidores a través de la API?
• ¿Qué acciones realizarán los consumidores en la API?

Por ejemplo, si se trata de una empresa de entrega de comida, quizás desee crear una API para su red de empresas asociadas, que les permita navegar y buscar en una base de datos de restaurantes para ofrecer un servicio de entrega.

En este ejemplo, su API va dirigida a socios de su empresa. Necesitarán manipular datos sobre restaurantes y realizar consultas de búsqueda sobre los datos, con ciertas capacidades de filtrado y clasificación.

Otro ejemplo: si su empresa ofrece un servicio SaaS de calendarios, es posible que desee crear una API para que otros desarrolladores front-end del mundo puedan crear nuevas aplicaciones móviles y web basadas en su sistema de calendario.

Pensar en los consumidores de su API es el primer paso para proporcionarles una buena experiencia de desarrollador. Esto ayudará a que su API destaque y aumente los niveles de interacción.

Los elementos que componen una API

Hay cuatro conceptos clave que se utilizan al diseñar una API:

• Un recurso es un elemento con el que sus consumidores interactuarán a través de su API. Los recursos se identifican de forma única mediante una ruta, que combinada con el punto de conexión de la API proporciona una dirección única para un recurso en la web. Por ejemplo, Calendarios es el nombre de un recurso que corresponde a una lista de calendarios, y su ruta es /calendars.
• Una operación es la acción que se puede realizar en sus recursos. Las operaciones más comunes son GET (leer), POST (crear), PUT (actualizar) y DELETE. Por ejemplo, List all Calendars es el nombre de una operación que utiliza el método GET en el recurso Calendars.
• Un tipo de datos es una descripción de los datos reales que se intercambian a través de la red. Por ejemplo, Calendar es el nombre de un tipo de datos que describirá todas las propiedades de un Calendario, como su nombre, propietario y una referencia a los eventos que le pertenecen. La operación List all Calendars devuelve una lista de tipos de datos Calendar.
• Un componente es un elemento que se puede reutilizar en toda la definición de la API. Por ejemplo, si necesita usar el mismo parámetro de consulta en varias operaciones, puede crearlo como un componente y referirse a él en tantas operaciones como sea necesario.

Hay otros elementos útiles que componen una API:

• Un punto de conexión es el punto de entrada principal para su API en la web. Un punto de conexión se compone de un esquema como HTTPS y un host como www.calendar-api.com.
• Un bloque de texto se puede usar para introducir libremente cualquier texto (incluido texto de marcado: markdown) que se pueda colocar en cualquier parte de su diseño de la API. Utilice bloques de texto para explicar temas transversales como la autenticación y el manejo de errores.
• Una Sección sirve para agrupar de forma significativa recursos y tipos de datos. Utilícelas para que el diseño de su API sea más claro y más fácil de usar para los desarrolladores. Puede arrastrar y soltar elementos en las secciones del panel izquierdo, y también puede reordenar las secciones entre sí.

En API Designer, podrá crear estos elementos desde el menú Crear nuevo en la esquina superior derecha.

Las URL de servidor se crean en la pantalla de información general. Una URL de servidor puede estar Publicada o No publicada. Si está publicada, aparece en la Documentación en vivo.