Introducción

¿Qué es una API?

API significa Application Programming Interface. Una API es un conjunto de reglas, protocolos, funciones y herramientas que permiten que diferentes aplicaciones se comuniquen entre sí y compartan datos o funcionalidades.

Una API actúa como un intermediario entre dos aplicaciones que desean intercambiar información (recursos) o realizar un conjunto de acciones a través de una interfaz.

Más información:

• API (Wikipedia)

¿Qué es una API Web?

Una API Web es un tipo de API que se utiliza específicamente para intercambiar información entre aplicaciones a través de la Web. En otras palabras, una API Web permite que diferentes aplicaciones se comuniquen y compartan datos a través de internet usando el protocolo HTTP y HTTPS como interfaz. En el caso de la Web entre el cliente, como por ejemplo un navegador Web o aplicación móvil y un servidor.

Una API Web se compone de una serie de puntos finales (endpoints) que representan los diferentes recursos que la API expone. Cada endpoint tiene una URL única y un conjunto de parámetros que se pueden utilizar para enviar y recibir información.

Los parámetros anexados a la URL del endpoint se conocen como query params, pero también se puede enviar datos en el cuerpo de la petición HTTP mediante el body.

¿Qué es una petición y una respuesta HTTP?

Cada intercambio de información entre dos entes en la Web empleando el protocolo HTTP se realizan a través de peticiones (request) y respuestas (response), estas tienen una estructura estandarizada para enviar y recibir información.

La petición consta de atributos como:

• El verbo HTTP
• La ruta que se desea acceder
• La versión del protocolo
• Los encabezados

La respuesta es muy similar, incluye adicionalmente:

• El código de respuesta
• El texto de la respuesta
• Diferentes encabezados
• La información o datos de la respuesta

Es bastante útil entender los componentes de estas, pues, son usados en gran parte por las API Web.

Códigos y verbos del protocolo HTTP

El protocolo HTTP (Hypertext Transfer Protocol) define un conjunto de verbos y códigos de estado que se emplean en las peticiones y respuestas entre un cliente y un servidor Web. Aquí hay una lista de los verbos HTTP y los códigos de estado más comunes:

Verbos HTTP:

• GET: solicita una representación de un recurso.
• POST: envía datos para crear un recurso nuevo en el servidor.
• PUT: envía datos para actualizar un recurso existente en el servidor.
• DELETE: elimina un recurso en el servidor.
• HEAD: solicita una respuesta similar a la de una solicitud GET, pero sin el cuerpo de la respuesta.
• OPTIONS: devuelve los métodos HTTP soportados por un recurso.
• PATCH: envía datos para actualizar parcialmente un recurso existente en el servidor.

Códigos de estado HTTP:

• 1xx (Respuestas informativas): indica que la solicitud fue recibida y el servidor continúa procesándola.
• 2xx (Respuestas exitosas): indica que la solicitud fue recibida, comprendida y aceptada con éxito.
• 3xx (Redirecciones): indica que se requiere tomar una acción adicional para completar la solicitud.
• 4xx (Errores del cliente): indica que la solicitud contenía datos incorrectos o no se pudo procesar.
• 5xx (Errores del servidor): indica que el servidor no pudo procesar la solicitud debido a un error en el servidor.

Algunos códigos de estado HTTP comunes son:

• 200 OK: indica que la solicitud fue procesada con éxito.
• 201 Created: indica que el servidor ha creado un nuevo recurso.
• 400 Bad Request: indica que la solicitud no se pudo entender debido a datos inválidos.
• 401 Unauthorized: indica que la solicitud no tiene una autenticación válida.
• 404 Not Found: indica que el servidor no pudo encontrar el recurso solicitado.
• 500 Internal Server Error: indica que el servidor encontró un error interno mientras procesaba la solicitud.

Más información:

• HTTP

¿Qué es una REST API Web?

Una REST API Web es un tipo de API Web que sigue un conjunto de principios y restricciones arquitectónicas denominados REST (Representational State Transfer) para facilitar la comunicación entre diferentes aplicaciones.

En una REST API Web, los recursos que la API expone se identifican mediante una URL única y se pueden acceder a través de los métodos HTTP estándar, como GET, POST, PUT y DELETE. Cada recurso tiene una representación en un formato estándar, como JSON, y los clientes pueden solicitar, enviar y manipular estos recursos a través de las peticiones HTTP.

Además, una REST API Web se rige por el principio de “estado sin sesión”, lo que significa que cada solicitud que se realiza al servidor debe contener toda la información necesaria para procesar la solicitud. No se mantiene ningún estado o contexto en el servidor entre solicitudes, lo que permite que la API sea fácilmente escalable.

Buenas prácticas de una REST API Web

Existen varias buenas prácticas que se deben seguir al diseñar una REST API Web para garantizar una buena funcionalidad, escalabilidad y seguridad, tales como:

1. Utilizar nombres en vez de verbos para representar los recursos significativos y consistentes: Los nombres de recursos en una REST API deben ser descriptivos y significativos, y se deben seguir convenciones de nomenclatura consistentes en todo la API y las colecciones se nombran en plural.
2. Utilizar verbos HTTP de forma consistente: Los verbos HTTP (GET, POST, PUT, DELETE, etc.) deben usarse de forma consistente para ejecutar operaciones CRUD (Create, Read, Update y Delete) en los recursos de la API.
3. Utilizar códigos de estado HTTP apropiados: Los códigos de estado HTTP deben emplearse de forma apropiada para indicar si una solicitud fue exitosa, si se produjo un error, si se requiere autenticación, etc.
4. Emplear JSON como formato de intercambio de información.
5. Utilizar la paginación para grandes conjuntos de datos: Si un conjunto de datos es demasiado grande para ser devuelto en una sola solicitud, se debe implementar la paginación para dividir los resultados en páginas más pequeñas.
6. Autenticación y autorización: Se debe usar autenticación y autorización para proteger la API contra accesos no autorizados y garantizar que solo los usuarios autorizados puedan acceder a los recursos de la API.
7. Documentación: Se debe proporcionar documentación clara y completa para la API, incluyendo información sobre los recursos disponibles, los parámetros de solicitud y las respuestas esperadas.

Un ejemplo de un contrato básico de REST Web API para el recurso de tareas llamado todos sería el siguiente:

Este contrato no es una camisa de fuerza, pero se deben respetar las definiciones básicas, no está permitido por ejemplo crear una tarea con el método DELETE en vez de POST, no tiene mucho sentido. Pero se pueden añadir muchas más operaciones, recursos anidados y demás, se dice que una API es RESTful cuando cumple con este contrato mínimo.

Más información:

• REST

Formato de la respuesta

No existe un estándar de respuesta para las RESTful Web APIs, pero una iniciativa llamada JSON API propone un formato de respuesta estandarizado que se puede utilizar para estructurar y formatear los datos de respuesta de la API.

El formato JSON API define una estructura clara y consistente para los datos de respuesta que incluye información sobre los recursos solicitados, los enlaces relacionados, los metadatos y los errores que puedan ocurrir. Esto hace que sea más fácil para los desarrolladores consumir la API y trabajar con los datos de respuesta.

Algunos de los componentes clave de una respuesta JSON API incluyen:

• data: la información de los recursos solicitados en formato JSON.
• links: los enlaces relacionados con la solicitud, como los enlaces a la siguiente página de resultados en caso de paginación.
• meta: los metadatos adicionales asociados con la solicitud, como la información de paginación o cualquier otra información relevante.
• errors: información sobre cualquier error que haya ocurrido en la solicitud, incluyendo un código de error, un mensaje de error y detalles adicionales sobre el error.

Además, JSON API también define convenciones para la paginación, ordenación, inclusión de relaciones y filtros de datos.

El uso de JSON API es opcional, pero puede ser útil para garantizar la interoperabilidad y la consistencia en la forma en que se estructuran las respuestas de la API.

Más información:

• JSON API

Formato de Error

Específicamente sobre el formato de respuesta del error existe un estándar de respuesta llamado Problem Details for HTTP APIs, también conocido como RFC 7807. Este estándar describe un formato para representar errores en una respuesta HTTP.

El formato estándar de la respuesta de error tiene la siguiente estructura:

• type: un enlace URI que identifica el tipo de problema.
• title: una descripción corta del problema.
• status: el código de estado HTTP que indica el tipo de error.
• detail: una descripción más detallada del problema.
• instance: una URI que identifica específicamente el recurso o la instancia que causó el problema.

Además, es posible incluir otros campos opcionales para proporcionar información adicional sobre el error, como por ejemplo:

• cause: una descripción del error raíz que causó el problema.
• suggestedAction: una sugerencia sobre cómo se puede solucionar el problema.
• invalidFields: una lista de campos de entrada que causaron el problema.

El uso de RFC 7807 ayuda a estandarizar la forma en que se manejan los errores en las respuestas de los RESTful Web APIs, lo que facilita la comprensión y el manejo de los errores por parte de los desarrolladores de aplicaciones y los usuarios finales.

Más información:

• RFC 7807

Glosario de términos

A continuación un listado de los términos mencionados anteriormente y los cuales utilizaremos de ahora en adelante:

• Recursos: Se refiere a la representación de la información que expone la API, según se mencionó en las mejores prácticas se utilizan nombres y no verbos como: todos, users, groups, etc.

• Entidad: Son los datos que representan la información del recurso, por ejemplo:

{
  "id": "1",
  "title": "Buy Milk"
}

• Colección: Las colecciones son un listado de entidades donde cada una de ellas tiene una misma estructura.

• Ruta: Es el fragmento de URL como se identifican los recursos o acciones que expone una API como: / (la raíz de la API), /api/todos, /api/groups/:id/todos, etc. Nótese que las rutas son relativas, es decir, que son independientes del dominio que se emplee para publicar la API.

• Endpoint: Este se refiere a la combinación entre el verbo HTTP y la ruta para poder acceder a un recurso o ejecutar una acción, de hecho se puede utilizar la misma ruta pero con verbos diferentes para expresar dos acciones diferentes:

  • GET /api/todos
  • POST /api/todos
  • PATCH /api/todos/:id

• Query params: Se mencionó en las buenas prácticas, que se pueden enviar parámetros anexados a la URL para indicar la paginación de las entidades devueltas por un endpoint, esto es precisamente utilizando query params:

  • GET /api/todos/?limit=20&offset=10

En el ejemplo anterior, se establecen dos parámetros para el endpoint que devuelve una colección de todos: limit con un valor de 20 limitara el número de entidades y offsetcon un valor de 10 indica el número de entidades a omitir en el resultado del endpoint.

• Body: Para enviar datos en el cuerpo de la petición, se utiliza el body junto con el encabezado para que el tipo de archivo sea interpretado como JSON.