Portada

APIs & ENDPOINTs

Un API (Interfaz de Programación de Aplicaciones, por sus siglas en inglés: Application Programming Interface) es un conjunto de reglas y especificaciones que permiten que diferentes aplicaciones de software se comuniquen e intercambien información entre sí, sin necesidad de que el usuario o el programador conozca los detalles internos de cómo funcionan esas aplicaciones.  

Piensa en un API como el camarero de un restaurante. Tú (una aplicación) le haces un pedido (una solicitud de información o una acción) al camarero (el API). El camarero va a la cocina (otra aplicación o sistema), le comunica tu pedido, recibe la respuesta (la información solicitada o el resultado de la acción) y te la entrega. Tú no necesitas saber cómo funciona la cocina ni cómo el camarero se comunica con ella; solo necesitas saber cómo hablar con el camarero (el API) para obtener lo que necesitas.

Un endpoint es una URL (Uniform Resource Locator) específica a la que una aplicación cliente envía una solicitud para acceder a una funcionalidad o recurso particular ofrecido por la API del servidor. Es el punto final de una conexión API, la ubicación exacta donde "golpeas" para pedir un servicio específico.

​Analogía: Imagina un restaurante. La API sería el menú. El menú lista todos los platos (funcionalidades) que el restaurante ofrece y describe cómo puedes pedirlos (los protocolos y formatos de datos). No te dice dónde está la cocina exactamente, pero te da las instrucciones para hacer tu pedido y qué esperar a cambio.

Utilidades de las APIs en Tecnología:

Las APIs son fundamentales en el mundo de la tecnología moderna y tienen una amplia gama de utilidades, entre las que destacan:

  • Integración de sistemas: Permiten que aplicaciones dispares, desarrolladas por diferentes equipos o incluso empresas, trabajen juntas. Por ejemplo, una aplicación de comercio electrónico puede usar la API de un proveedor de pagos para procesar transacciones sin tener que implementar su propio sistema de pagos.
  • Reutilización de funcionalidades: Los desarrolladores pueden aprovechar las funcionalidades existentes de otras aplicaciones a través de sus APIs, en lugar de tener que construir todo desde cero. Esto ahorra tiempo, esfuerzo y recursos. Por ejemplo, una aplicación de mapas puede utilizar la API de Google Maps para mostrar mapas y calcular rutas.
  • Modularidad y flexibilidad: Las APIs fomentan la creación de sistemas modulares, donde diferentes componentes (aplicaciones o servicios) pueden ser desarrollados y actualizados de forma independiente sin afectar necesariamente a otros componentes. Esto facilita el mantenimiento y la evolución de las aplicaciones.
  • Innovación y creación de nuevos servicios: Las APIs abren la puerta a la creación de nuevas aplicaciones y servicios combinando funcionalidades de diferentes plataformas. Por ejemplo, aplicaciones que integran datos de redes sociales, mapas y servicios de localización.
  • Acceso a datos y funcionalidades de terceros: Las APIs permiten acceder a datos y funcionalidades ofrecidas por otras empresas o plataformas. Por ejemplo, acceder a datos meteorológicos a través de una API del servicio meteorológico o publicar contenido en redes sociales a través de sus APIs.
  • Automatización de tareas: Las APIs permiten automatizar tareas y flujos de trabajo entre diferentes aplicaciones. Por ejemplo, automatizar la creación de tickets de soporte en un sistema de gestión de incidencias cuando se recibe un nuevo correo electrónico.
  • Desarrollo de aplicaciones móviles: Las APIs son cruciales para el desarrollo de aplicaciones móviles, ya que permiten que las aplicaciones accedan a datos y funcionalidades de servidores y otros servicios en la nube.
  • Arquitecturas de microservicios: En arquitecturas de microservicios, las APIs son el principal mecanismo de comunicación entre los diferentes servicios independientes que componen una aplicación.

En resumen, las APIs son la base de la interoperabilidad en el mundo digital. Permiten que diferentes sistemas y aplicaciones se conecten, compartan información y trabajen juntos de manera eficiente, impulsando la innovación, la automatización y la creación de nuevas y mejores experiencias para los usuarios. Son un componente esencial de la infraestructura tecnológica moderna.

Tipos de métodos utilizados en las llamadas a ENDPOINTs

Hablando de los métodos HTTP (a menudo denominados "verbos") que se pueden utilizar en las APIs RESTful y su significado. Estos métodos indican la acción que el cliente desea realizar en el recurso identificado por la URL del endpoint.

Los métodos HTTP más comunes y sus significados son:

  • GET:

    • Significado: Se utiliza para solicitar la representación de un recurso específico. Es el método más común y se utiliza para obtener datos del servidor.
    • Características:
      • Debería ser idempotente, lo que significa que realizar la misma solicitud GET varias veces debería producir el mismo resultado (sin efectos secundarios en el servidor).
      • Generalmente no tiene cuerpo de solicitud (aunque algunos frameworks lo permiten, no es la práctica estándar).
      • Las respuestas a menudo se pueden almacenar en caché.
      • Permiten enviar variables en la url ?var1=valor1&var2=valor (estas variables se llaman _GET params)

  • POST:

    • Significado: Se utiliza para enviar datos al servidor para crear un nuevo recurso. También puede utilizarse para enviar datos para ser procesados, sin necesariamente crear un nuevo recurso.
    • Características:
      • No es idempotente. Realizar la misma solicitud POST varias veces podría tener efectos secundarios diferentes (por ejemplo, crear múltiples recursos idénticos).
      • Tiene cuerpo de solicitud que contiene los datos a enviar al servidor (con diferentes formatos: form-params, raw:JSON, etc..)
      • Las respuestas a menudo incluyen un código de estado 201 Created y la ubicación del nuevo recurso en el encabezado Location.

  • PUT:

    • Significado: Se utiliza para enviar datos al servidor para actualizar un recurso existente. La solicitud PUT debe contener la representación completa del recurso actualizado. Si el recurso no existe, el servidor podría crearlo (aunque esto no es estrictamente requerido por la especificación HTTP y a menudo se prefiere usar POST para la creación).
    • Características:
      • Debería ser idempotente. Realizar la misma solicitud PUT varias veces debería producir el mismo estado final del recurso.
      • Tiene cuerpo de solicitud que contiene la representación completa del recurso actualizado.
      • Las respuestas a menudo incluyen 200 OK (si la modificación fue exitosa) o 204 No Content. Si se creó un nuevo recurso, podría devolverse 201 Created.

  • DELETE:

    • Significado: Se utiliza para solicitar la eliminación de un recurso específico en el servidor.
    • Características:
      • Debería ser idempotente. Realizar la misma solicitud DELETE varias veces debería tener el mismo resultado (el recurso ya está eliminado), aunque las respuestas posteriores podrían ser 204 No Content.
      • Generalmente no tiene cuerpo de solicitud.
      • Las respuestas a menudo incluyen 200 OK (si la eliminación fue exitosa) o 204 No Content.

Además de estos métodos principales, existen otros que se utilizan con menos frecuencia:

  • HEAD:

    • Significado: Es similar a GET, pero solicita solo los encabezados de la respuesta, sin el cuerpo.
    • Características: Útil para verificar la existencia de un recurso, obtener metadatos (como el tipo de contenido, la fecha de modificación, el tamaño) sin descargar el contenido real. Debe ser idempotente y no tener cuerpo de solicitud.

  • OPTIONS:

    • Significado: Se utiliza para solicitar información sobre las opciones de comunicación disponibles para un recurso específico. El servidor responde con los métodos HTTP que soporta el recurso (en el encabezado Allow).
    • Características: Útil para que el cliente determine qué acciones puede realizar en un endpoint. Puede tener cuerpo de solicitud, pero no es común.

  • PATCH:

    • Significado: Se utiliza para aplicar modificaciones parciales a un recurso existente. A diferencia de PUT, que reemplaza toda la representación del recurso, PATCH solo envía los cambios específicos.
    • Características:
      • No es necesariamente idempotente. Aplicar la misma secuencia de parches varias veces podría tener resultados diferentes.
      • Tiene cuerpo de solicitud que contiene las instrucciones de modificación.
      • Las respuestas a menudo incluyen 200 OK (si la modificación fue exitosa) o 204 No Content.

  • CONNECT:

    • Significado: Establece un túnel a un servidor identificado por el recurso objetivo. Se utiliza principalmente con proxies para establecer conexiones seguras (por ejemplo, para HTTPS).

  • TRACE:

    • Significado: Realiza una prueba de bucle de retorno del mensaje para ver qué servidores intermedios están recibiendo y modificando la solicitud. Principalmente utilizado para diagnóstico.

La mayoría de las APIs RESTful se basan en los cuatro métodos principales (GET, POST, PUT, DELETE) para realizar operaciones CRUD (Crear, Leer, Actualizar, Eliminar) sobre los recursos. La elección del método HTTP correcto es fundamental para diseñar APIs intuitivas y semánticamente correctas. ¡Espero que esta explicación te sea útil en este miércoles por la mañana en Rivas!

Códigos de respuesta y su significado

Cuando un cliente (como un navegador web, una aplicación móvil o incluso otro servidor) realiza una solicitud a una API web, el servidor responde con un código de estado HTTP de tres dígitos. Este código indica el resultado de la solicitud y ayuda al cliente a entender qué ocurrió.

Los códigos de respuesta se agrupan en cinco categorías, según el primer dígito:

1xx: Informativas (Informational)

Estos códigos indican que la solicitud fue recibida y se está procesando. Son poco comunes en las respuestas típicas de las APIs.

2xx: Éxito (Successful)

Estos códigos indican que la solicitud del cliente fue recibida, entendida y aceptada con éxito.

3xx: Redirección (Redirection)

Estos códigos indican que se deben tomar acciones adicionales por parte del cliente para completar la solicitud. A menudo, esto implica una redirección a una nueva URL.

4xx: Error del Cliente (Client Error)

Estos códigos indican que la solicitud contenía una sintaxis incorrecta o no pudo ser cumplida por el servidor. Son errores que generalmente pueden ser corregidos por el cliente.

5xx: Error del Servidor (Server Error)

Estos códigos indican que el servidor encontró un error o no pudo cumplir con la solicitud válida del cliente. Son errores que generalmente son culpa del servidor.

En resumen, los códigos de respuesta de una API HTTP son cruciales para que el cliente entienda el resultado de su solicitud. Los códigos 2xx indican éxito, los 3xx indican redirecciones, los 4xx indican errores del cliente y los 5xx indican errores del servidor. Al entender estos códigos, los desarrolladores pueden construir aplicaciones más robustas y capaces de manejar diferentes escenarios de comunicación con las APIs.

Detalle de los códigos de respuesta

  • 100 Continue: El servidor ha recibido los encabezados de la solicitud y el cliente debe continuar enviando el cuerpo (si lo hay).
  • 101 Switching Protocols: El servidor está cambiando los protocolos según lo solicitado por el cliente en el encabezado Upgrade.
  • 102 Processing: El servidor ha recibido y está procesando la solicitud, pero aún no hay una respuesta disponible. Se utiliza para evitar que el cliente piense que la solicitud se ha perdido.
  • 103 Early Hints: Se utiliza para devolver algunos encabezados de respuesta antes de la respuesta HTTP final.
  • 200 OK: La solicitud tuvo éxito. El significado del éxito varía según el método HTTP utilizado:
    • GET: La información solicitada se ha devuelto en el cuerpo de la respuesta.
    • POST: Se ha creado un nuevo recurso como resultado de la solicitud. La respuesta suele contener detalles del nuevo recurso.
    • PUT: El recurso existente se ha modificado con éxito. La respuesta suele ser 200 OK o 204 No Content.
    • DELETE: El recurso se ha eliminado con éxito. La respuesta suele ser 200 OK o 204 No Content.
  • 201 Created: La solicitud tuvo éxito y se ha creado un nuevo recurso. La respuesta debe incluir detalles del nuevo recurso y su ubicación (a través del encabezado Location).
  • 202 Accepted: La solicitud ha sido aceptada para su procesamiento, pero el procesamiento aún no ha finalizado. La respuesta no garantiza que el procesamiento finalizará con éxito. Suele incluir un encabezado Location que indica cómo monitorizar el estado de la solicitud.
  • 203 Non-Authoritative Information: El servidor ha procesado la solicitud con éxito, pero la información de la respuesta puede provenir de una fuente diferente al servidor de origen (por ejemplo, una caché).
  • 204 No Content: El servidor ha procesado la solicitud con éxito, pero no devolverá ningún contenido en el cuerpo de la respuesta. Los encabezados pueden estar presentes. Se utiliza a menudo para acciones exitosas que no requieren una actualización de la interfaz de usuario.
  • 205 Reset Content: El servidor ha procesado la solicitud con éxito y el cliente debe restablecer la vista del documento (por ejemplo, limpiar un formulario).
  • 206 Partial Content: El servidor ha entregado solo una parte del recurso solicitado, según los encabezados de rango enviados por el cliente.
  • 207 Multi-Status (WebDAV): La respuesta contiene información sobre el estado de múltiples recursos en una operación.
  • 208 Already Reported (WebDAV): Los miembros de un enlace-mi-multistatus ya han sido enumerados en una parte anterior de la respuesta multi-status y no se están incluyendo de nuevo.
  • 300 Multiple Choices: El recurso solicitado tiene múltiples representaciones posibles. El cliente (o el agente de usuario) puede elegir una de ellas.
  • 301 Moved Permanently: El recurso solicitado ha sido movido permanentemente a una nueva URL. El cliente debe utilizar esta nueva URL para futuras solicitudes. La respuesta debe incluir la nueva URL en el encabezado Location.
  • 302 Found (Antes "Moved Temporarily"): El recurso solicitado reside temporalmente bajo una URL diferente. El cliente debe seguir la URL proporcionada en el encabezado Location para esta solicitud, pero debe seguir utilizando la URL original para futuras solicitudes.
  • 303 See Other: La respuesta a la solicitud se puede encontrar bajo otra URL utilizando el método GET. Se utiliza a menudo después de una solicitud POST para evitar el reenvío del formulario. La respuesta debe incluir la nueva URL en el encabezado Location.
  • 304 Not Modified: El cliente ha realizado una solicitud condicional (generalmente con encabezados If-Modified-Since o If-None-Match) y el recurso no ha sido modificado desde la última vez que el cliente lo accedió. El servidor no envía el cuerpo del recurso.
  • 307 Temporary Redirect: El recurso solicitado reside temporalmente bajo una URL diferente, y el cliente debe utilizar el mismo método HTTP que se utilizó en la solicitud original para realizar la solicitud a la nueva URL. La respuesta debe incluir la nueva URL en el encabezado Location.
  • 308 Permanent Redirect: El recurso solicitado ha sido movido permanentemente a una nueva URL, y el cliente debe utilizar el mismo método HTTP que se utilizó en la solicitud original para realizar futuras solicitudes a la nueva URL. La respuesta debe incluir la nueva URL en el encabezado Location.
  • 400 Bad Request: El servidor no pudo entender la solicitud debido a una sintaxis inválida. El cliente no debe repetir la solicitud sin modificaciones.
  • 401 Unauthorized: El cliente no está autenticado. Debe proporcionar credenciales válidas para acceder al recurso solicitado. La respuesta debe incluir un encabezado WWW-Authenticate que indica el esquema de autenticación.
  • 402 Payment Required: Este código está reservado para uso futuro.
  • 403 Forbidden: El servidor entendió la solicitud, pero se niega a autorizarla. A diferencia de 401 Unauthorized, la identidad del cliente es conocida, pero no tiene los permisos necesarios para acceder al recurso.
  • 404 Not Found: El servidor no pudo encontrar el recurso solicitado en la URL. Este es uno de los códigos más comunes.
  • 405 Method Not Allowed:El método HTTP utilizado en la solicitud no está permitido para el recurso especificado. La respuesta debe incluir un encabezado.
  • 406 Not Acceptable: El servidor no puede producir una respuesta en ninguno de los formatos aceptados por el cliente, según los encabezados Accept enviados en la solicitud.
  • 407 Proxy Authentication Required: El cliente debe autenticarse con el servidor proxy antes de que se pueda reenviar la solicitud al servidor de origen.
  • 408 Request Timeout: El servidor esperó la solicitud del cliente dentro del tiempo de espera configurado, pero no la recibió completamente. El cliente puede repetir la solicitud en un momento posterior.
  • 409 Conflict: La solicitud no pudo completarse debido a un conflicto con el estado actual del recurso (por ejemplo, intentar actualizar un recurso con información inconsistente).
  • 410 Gone: El recurso solicitado ya no está disponible en el servidor y no se espera que vuelva a estarlo. Los clientes no deben intentar acceder al recurso en el futuro.
  • 411 Length Required: El servidor requiere que el cliente especifique la longitud del cuerpo de la solicitud a través del encabezado Content-Length.
  • 412 Precondition Failed: Una o más de las precondiciones especificadas en los encabezados de la solicitud (If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, If-Range) se evaluaron como falsas.
  • 413 Payload Too Large (Antes "Request Entity Too Large"): El cuerpo de la solicitud es más grande de lo que el servidor está dispuesto o puede procesar.
  • 414 URI Too Long (Antes "Request-URI Too Long"): La URI de la solicitud es demasiado larga para que el servidor la procese.
  • 415 Unsupported Media Type: El formato del cuerpo de la solicitud no está soportado por el servidor para el recurso solicitado. El cliente debe enviar los datos en un formato soportado.
  • 416 Range Not Satisfiable: El rango especificado en el encabezado Range no se puede satisfacer (por ejemplo, si el rango está fuera del tamaño del recurso).
  • 417 Expectation Failed: La expectativa indicada por el encabezado Expect no puede ser cumplida por el servidor.
  • 418 I'm a teapot (RFC 2324): Este código fue definido en una broma del April Fools

  • 500 Internal Server Error: El servidor encontró una condición inesperada que le impidió cumplir con la solicitud. Es un código de error genérico que indica un problema en el servidor, pero no se especifica la naturaleza exacta del error. La respuesta a menudo contiene más detalles sobre el error.  

  • 501 Not Implemented: El servidor no soporta la funcionalidad requerida para cumplir con la solicitud (por ejemplo, un método HTTP desconocido para el servidor). La respuesta debe incluir un encabezado Allow que indica los métodos que el servidor soporta para el recurso solicitado.

  • 502 Bad Gateway: El servidor, mientras actuaba como una puerta de enlace o proxy, recibió una respuesta inválida del servidor upstream al que accedió para completar la solicitud. Esto a menudo indica un problema de comunicación entre servidores.  

  • 503 Service Unavailable: El servidor no está disponible actualmente para manejar la solicitud. Esto puede deberse a una sobrecarga temporal o a un mantenimiento programado. La respuesta puede incluir un encabezado Retry-After que indica cuánto tiempo debe esperar el cliente antes de volver a intentarlo.

  • 504 Gateway Timeout: El servidor, mientras actuaba como una puerta de enlace o proxy, no recibió una respuesta oportuna del servidor upstream al que accedió para completar la solicitud. Esto puede deberse a un problema de red o a que el servidor upstream está sobrecargado o no funciona.

  • 505 HTTP Version Not Supported: El servidor no soporta la versión del protocolo HTTP utilizada en la solicitud.

  • 506 Variant Also Negotiates (RFC 2295): Se ha detectado una negociación transparente para la propia variante, lo cual no es sensato.

  • 507 Insufficient Storage (WebDAV): El servidor no puede almacenar la representación necesaria para completar la solicitud.

  • 508 Loop Detected (WebDAV): El servidor detectó un bucle infinito al procesar la solicitud (por ejemplo, una cadena de redirecciones).

  • 510 Not Extended (RFC 2774): Se requieren más extensiones para que el servidor pueda cumplir con la solicitud.

  • 511 Network Authentication Required (RFC 6585): El cliente necesita autenticarse para obtener acceso a la red. A menudo se utiliza en portales Wi-Fi públicos donde se requiere iniciar sesión antes de acceder a Internet.

  • 599 Network Connect Timeout Error: Este código no es estándar, pero es utilizado por algunos proxies HTTP para indicar un error de timeout de conexión de red detrás del proxy al servidor.

Cesta de compras