Qué es un API y cómo funciona


En términos de programación, una API nos ayuda "a los Frontend" a solicitar un dato o recurso específico generado por el backend. Significa application programming interface y esto traduce a interfaz de programación de aplicaciones, es netamente código preparado en el servidor para entregar y ofrecer datos que puedan ser consumidos por otro sistema.

La clave es entenderlo como un proceso de integración, es decir, creamos un API en nuestro proyecto web para que luego podamos usar o consumir el contenido en una aplicación de celular, iPad o cualquier otro software y dispositivo. Otra forma de decirlo es que las API nos ayudan a que nuestro proyecto se pueda comunicar con otro sin la necesidad de conocer cómo están implementados o programados.

youtube

Ejemplo:

  1. Mi proyecto rimorsoft.com.
  2. Quiero desarrollar una app que muestre los artículos aquí redactados.
  3. En rimorsoft.com desarrollo el API que entregue esta información.
  4. En la aplicación me conecto a la ruta que proporciona dicha información.

En este ejemplo ¿Cuál es el API? Es el código desarrollado en el servidor que entrega los artículos a través de una ruta o dirección.

Podemos usar las API conocidas en el mercado, veamos unos elementos con ejemplos:

  1. Conectarse a la plataforma de pagos para verificar un depósito realizado.
  2. API de youtube para obtener información sobre tu canal.
  3. API de Instagram para obtener estadísticas del perfil.
  4. API de Google Maps para obtener datos de geolocalización y poder trazar rutas, visualizar un mapa, etc.
  5. ...

Nota que en todos los casos son aplicaciones o código preparado que podemos simplemente utilizar, es en esencia aprovechar el desarrollo en alguna aplicación. Permite que diferentes sistemas se puedan comunicar.

Convención

Endpoint: (punto final) son las rutas para consumir datos de un API, estas básicamente responden a una petición. En términos sencillos son las rutas que preparas y que apuntan a un controlador.

VERB: /api/endpoint

Verb significa VERBO y hace referencia directamente al verbo HTTP, estos son: GET, POST, PUT, PATCH y DELETE. Estos indican la intención, puedes ver que en la ruta tenemos parámetros y estos a menudo los utilizamos para ordenar o filtrar. Para dar un ejemplo más preciso veamos una ruta para consultar artículos desde el backend de una página como rimorsoft.

GET: /api/posts

Respuesta en JSON:

{
    "data": [
        {
            "id": 1,
            "attributes": {
                "title": "Crea un API, qué es y para que sirven",
                "url": "crea-un-api-que-es-y-para-que-sirven",
                "body": "Lorem ipsum...",
                "created": "2021-09-03 00:00:00",
                "updated": "2021-09-03 00:00:00"
            }
        },
        {
            "id": 2,
            "attributes": {
                "title": "Clean Code",
                "url": "clean-code",
                "body": "Lorem ipsum...",
                "created": "2021-09-03 00:00:00",
                "updated": "2021-09-03 00:00:00"
            }
        }
    ]
}

Veamos esta ruta en un ejemplo con parámetros.

GET: /api/posts?include=author

Esta respuesta puede ser en XML, pero tomemos en cuenta que JSON es el estándar actual, hay casos incluso en los que el cliente te exige un resultado en texto plano.

Verbos HTTP

Mencioné los métodos utilizados, pero en esta sección le dedicaremos algunos textos a los verbos HTTP, estos juegan un papel importante porque nos ayuda a declarar la intención en la solicitud. Básicamente el verbo HTTP le dice al servidor cómo nosotros desde el lado del cliente, pretendemos manejar nuestros datos.

La forma de manejar los datos a menudo se analiza desde una perspectiva CRUD, que significa: Crear, Leer, Actualizar, Eliminar.

  • GET: Nos ayuda a indicar que vamos simplemente a leer los datos. Eso es lo único que este verbo le dice a nuestro servidor.
  • POST: Es el método usado para crear un recurso. En otras palabras, usamos POST siempre que queremos transferir nuevos datos del cliente al servidor.
  • PUT y PATCH: PUT y PATCH son para indicar que vamos a actualizar o modificar datos, pero están pensadas para diferentes situaciones.

Detalles

  1. PUT se utiliza cuando todos los datos de un recurso se reemplazan por completo, actualización total.
  2. PATCH se utiliza para una actualización o modificación parcial, en lugar de reemplazar todo el recurso.

El uso de PUT o PATCH depende de ti y de las necesidades puntuales. Las diferencias son sutiles, pero están ahí para dejar completamente clara nuestra intención.

  • DELETE: Como su nombre lo indica, nos ayuda para indicar que vamos a eliminar un recurso o registro.

Estados HTTP

Recuerda que los verbos HTTP nos ayudan a indicar nuestra intención desde el dispositivo o software cliente, ahora veamos cómo el servidor le informa al cliente sobre las solicitudes a través de códigos (estados HTTP). El servidor utiliza códigos para indicarle al cliente si una solicitud se ha completado correctamente.

1XX - Informativo

Su objetivo es proporcionar información respecto a la solicitud, la usamos con muy poca frecuencia, el estado más común es el código 100 que indica que el navegador puede continuar realizando la petición.

2XX - Éxito

El rango 2XX son estados que indican que una solicitud se realizó correctamente.

200 OK: Dice que una solicitud fue exitosa, es el estado más común.

201 Creado: Con este estado indicamos que se ha creado correctamente algún recurso.

204 Sin contenido: Este código indica que la solicitud se ha cumplido con éxito pero que no tiene alguna respuesta detallada. Podemos usarlo al momento de actualizar un recurso.

3XX - Redireccionamiento

El rango 3XX informa al cliente sobre los redireccionamientos. Podemos indicar actualización temporal o permanente de alguna dirección.

301 Movido permanentemente: Con este código decimos al cliente que hemos movido dicha dirección o otra y que este cambio será permanente.

302 Movido temporalmente: Con este código decimos al cliente que la ruta visitada seguirá existiendo pero por algún motivo la hemos movido a otra dirección de manera temporal.

303 Redirección a otros elementos: Se trabaja con una redirección a un nuevo recurso usando una petición GET.

307 Redirección temporal: En este caso hablamos de una redirección temporal. Con este código proporcionamos una nueva ruta pero sin guardar ninguna referencia a la redirección. En esta redirección debemos mantener el verbo HTTP original.

308 Redirección permanente: Se trata de la redirección permanente, trabaja como el código 301 solo que en este caso debemos mantener el verbo HTTP original.

4XX - Errores del lado del cliente

El rango 4XX trata con los errores que podrían ser de una solicitud en la que el cliente necesite iniciar sesión o que ha intentado buscar una página que no existe.

400 Solicitud incorrecta: Con este código simplemente informamos que no se pudo procesar la solicitud sin mayor detalle.

401 No autorizado: Con este código le decimos al cliente que necesita iniciar sesión.

403 Prohibido: Este código se observa con frecuencia cuando queremos ver por ejemplo el contenido de una carpeta directamente y sin permiso. También podríamos usarlo para indicar que el acceso es restringido, es decir, puede estar con su usuario dado de alta e iniciado pero no tiene los permisos necesarios.

404 no encontrado: Este código indica que no se pudo conseguir el recurso solicitado.

405 Método no permitido: Con este código indicamos que el verbo HTTP usado no está permitido. Este código podría surgir cuando intentamos por ejemplo hacer una solicitud POST pero el sistema la está esperando como GET.

422 Entidad no procesable: Con este código indicamos que la solicitud es correcta pero no se pudo procesar o completar, quizás debido a alguna validación programada.

5XX - Errores del lado del servidor

El rango 5XX tiene todos los estados relacionados con el código en el servidor.

500 Error interno del servidor: Este es el error genérico que aparece cuando no sabemos con certeza que está sucediendo en el servidor.

503 Servicio no disponible: Usamos este código con mucha frecuencia para indicar que estamos inactivos por mantenimiento.

REST

REST significa Representational State Transfer y es un estilo arquitectónico que utilizamos comúnmente para la comunicación entre un cliente y un servidor. Solo debemos entender que al mencionar REST nos referimos a una arquitectura que utiliza a HTTP como protocolo de comunicación.

Todo lo que hemos explicado son conceptos dentro de esta arquitectura llamada REST, se trata de esperar solicitudes o peticiones y responderlas con XML o JSON.

Cuando oigas RESTful puedes pensar en un sinónimo, sin embargo, quien conoce el término lo usa para referirse a una aplicación o servicio web que se ejecuta o funciona con la arquitectura REST.

REST es una arquitectura que trabaja sobre HTTP y por ello usa sus estados para comunicar qué ha sucedido con la solicitud realizada, con ello quiero decir que todo lo aprendido aplica al construir una API, verbos, intención de una solicitud o petición, estados HTTP más comunes, etc.

Este es el conocimiento que necesitas para escribir un API correctamente.

Compartir en: Facebook Twitter