# ¿Qué es una API?

## Interfaz de Programación de Aplicaciones

Interfaz de Programación de Aplicaciones (API), es un contrato que permite a un código comunicarse con otro código. Las API son los componentes básicos del software moderno porque permiten compartir recursos y servicios entre aplicaciones, organizaciones y dispositivos.

## ¿Por qué son importantes las API's?

1. Las APIs ayudan a los desarrolladores a **integrar funcionalidades** y **crear automatizaciones** sin tener que reinventar la rueda constantemente.
2. Permiten a las empresas **abrir sus productos para innovar más rápido**.
3. Pueden ser por si mismas **un producto**.

En última instancia, todo el mundo se beneficia de las API, ya sea directa o indirectamente, porque las API hacen que los procesos sean más eficientes y conectan los servicios que amamos y en los que confiamos.

<figure><img src="https://3564053473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhfO9EOwki7wFia7nyJu4%2Fuploads%2FWwXfUYWYVTnvQJZli2m8%2Fimage.png?alt=media&#x26;token=a5d5b620-9962-44a0-b4d5-f00b50f8f1c4" alt=""><figcaption><p>Ejemplo de una API - Un restaurante digital</p></figcaption></figure>

Un cliente que quiere sopa no va a la cocina a cocinar. Ni siquiera tiene que saber hacer sopa. Sólo tiene que saber pedir sopa al camarero y esperar que éste se la traiga.

Las API funcionan de la misma manera, pero los actores implicados reciben nombres diferentes. En lugar de sopa, el solicitante puede pedir datos o la ejecución de un servicio.

| Client | El solicitante. *Ex: Navegador, web app, mobile app* | Cliente  |
| ------ | ---------------------------------------------------- | -------- |
| API    | Interfaz simplificada para actuar con el backend     | Camarero |
| Server | El backend donde se procesa nuestra petición         | Cocina   |

## &#x20;Tipos de APIs

Aunque este curso se centrará en las API web, es importante saber que "API" puede aplicarse a una amplia gama de interfaces:

**Hardware APIs**: Interfaz para que el software se comunique con el hardware. Ej: Como la cámara de tu móvil se comunica con tu S.O.

**Software Library APIs**: Interfaz que consume código directamente de otra fuente de código. Ej: Importar métodos de una librería en tu app.

**Web APIs**: Interfaz de comunicación entre código fuente a través de la red.

## Arquitecturas

Existen varios tipos de construcción y maneras de consumir una API.

* REST (Representational State Transfer)
* GraphQL
* WebSockets
* Webhooks
* SOAP (Simple Object Access Protocol)
* gRPC (Google Remote Procedure Call)
* MQTT (MQ Telemetry Transport)

## API REST

### Accesos

Las APIs también varían en cuestión de quien puede acceder a ellas:

* APIs Públicas (también conocidas como APIs Abiertas): Estas APIs pueden ser consumidas por cualquiera que tenga acceso a ellas.
* APIs Privadas: Consumidas solo por la organización y no accesibles para todos los públicos.
* APIs de Socios: Consumido entre una o mas organizaciones que tienen una relación establecida.

La API que utilizaremos en este curso será una API Pública, REST, Web.

## Plataforma API

Una plataforma API sirve para construir y utilizar APIs (por ejemplo, POSTMAN). Una plataforma API (simplifica cada paso del ciclo de vida de las API y agiliza la colaboración para que pueda crear mejores API más rápidamente y consumirlas con facilidad.

<figure><img src="https://voyager.postman.com/illustration/what-is-postman-illustration-4.svg" alt=""><figcaption><p>Ciclo de Vida de una API de Software</p></figcaption></figure>

Trabajar con APIs, antes y ahora: cURL vs. Postman

Antes de que aparecieran las plataformas de API (postman), era una práctica común hurgar en las APIs con una herramienta en línea de comandos para hacer peticiones HTTP llamada **cURL**. Esta herramienta se sigue utilizando hoy en día, pero tiene sus limitaciones cuando se trata de colaborar y compartir.

### **Llamadas con API `curl`**

Ejemplo de una llamada usando **`curl`** en una terminal.

**curl <https://api.github.com/users/postmanlabs>**

<figure><img src="https://3564053473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhfO9EOwki7wFia7nyJu4%2Fuploads%2F6WhiY0ikksKsWcrDZcEf%2Fimage.png?alt=media&#x26;token=e2af270a-98b9-45fe-95d8-4cd8eb74f626" alt=""><figcaption><p>Salida por pantalla del comando cURL</p></figcaption></figure>

Funciona muy bien, pero una vez que haces la llamada, los datos de respuesta de la API se pierden en la terminal y tampoco tienes visibilidad de los metadatos de la respuesta sino añades más parámetros al comando ejecutado.

### Llamadas API con Postman

Aquí está la misma llamada hecha con la plataforma de APIs Postman. Postman muestra la respuesta con sangrías y colores limpios y te permite guardar, organizar y compartir tus peticiones. También puedes ver todos los componentes de la solicitud y la respuesta desglosados en pestañas y otros detalles útiles como el tiempo de respuesta y el código de estado.

<figure><img src="https://3564053473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhfO9EOwki7wFia7nyJu4%2Fuploads%2FEPY72RJnrlv2TbYCGmT4%2Fimage.png?alt=media&#x26;token=dde6d7c2-3854-4f58-ae16-0863a12d66d3" alt=""><figcaption><p>Captura de pantalla de salida de muestra de una petición en POSTMAN</p></figcaption></figure>

## El mundo del paradigma "API First"

Postman tiene la visión de un mundo en el que las API sean lo primero: un mundo en el que 100 millones de desarrolladores estén conectados a través de API, y en el que las API ocupen un lugar central como principales bloques de construcción. En el mundo de la API primero:

<figure><img src="https://3564053473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhfO9EOwki7wFia7nyJu4%2Fuploads%2FU96O9VPQYv4pj9Rak7ZI%2Fimage.png?alt=media&#x26;token=a6306617-41fa-49e0-b23f-c1f6a17bc60e" alt=""><figcaption><p>The API-First World Postman Captura</p></figcaption></figure>

## La respuesta de una API

Si todo va bien, verás una respuesta del servidor en la mitad inferior de Postman.

Debería tener este aspecto: un cuerpo de respuesta **JSON** (JavaScript Object Notation) con un array de objetos libro. Puedes desplazarte hacia abajo para ver más libros.

<figure><img src="https://3564053473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhfO9EOwki7wFia7nyJu4%2Fuploads%2FdlKbMAVQjyyOsaP8jLie%2Fimage.png?alt=media&#x26;token=cdca0108-f200-48b8-88ba-ee25782c4351" alt=""><figcaption><p>Captura de un Objeto JSON tras una llamada a una API por el método GET</p></figcaption></figure>

## Métodos de Solicitud (Request Methods)

Cuando hacemos una llamada HTTP a un servidor, especificamos un método de petición que indica el tipo de operación que vamos a realizar.&#x20;

Algunos métodos de petición HTTP comunes corresponden a las operaciones CRUD mencionadas anteriormente. Puedes ver una lista de más métodos [aquí](https://desarrollo.alberlome.com/conocimientos/metodos-http-request).

| `GET`       | Obtener datos (**R**ead)                                                                                                                                                |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST`      | Enviar datos (**C**reate)                                                                                                                                               |
| `PUT/PATCH` | <p>Actualizar datos (<strong>U</strong>pdate)<br><br>\* <code>PUT</code> sustituye un recurso entero, mientras que<code>PATCH</code> hace una actualización parcial</p> |
| `DELETE`    | Eliminar datos (**D**elete)                                                                                                                                             |

Dado que en nuestra prueba estamos "obteniendo" libros y no modificando ningún dato, **tiene sentido que hagamos una petición GET**.

Esto son sólo convenciones, **todo depende de cómo esté codificada la API**. Para saber qué método utilizar, lea siempre la documentación de la API con la que esté trabajando.

## Solicitar una URL (Request URL)

Además de un método de solicitud, una solicitud debe incluir una **URL de solicitud** que indique dónde realizar la llamada a la API. Una URL de solicitud consta de tres partes:&#x20;

* un protocolo (como http\:// o https\://)
* host (ubicación del servidor)
* path (ruta en el servidor).&#x20;

En la API REST de ejemplo, la ruta suele apuntar a una entidad de referencia, como "libros".

| Protocolo  | Host                          | Path     |
| ---------- | ----------------------------- | -------- |
| `https://` | `library-api.postmanlabs.com` | `/books` |

#### Códigos de Respuesta del Servidor

Los códigos de estado son indicadores de si una solicitud ha fallado o ha tenido éxito. Los códigos de estado tienen convenciones. Por ejemplo, cualquier código de estado que empiece por "2xx" (una "respuesta de nivel 200") representa una llamada correcta. Familiarízate con otras categorías de códigos de estado:<br>

| Rango del código | **Significado** | **Ejemplo**                                                                                                                                  |
| ---------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `2xx`            | Success         | <p><code>200</code> - OK<br><code>201</code> - Created<br><code>204</code> - No content (silent OK)</p>                                      |
| `3xx`            | Redirection     | <p><code>301</code> - Moved (path changed)<br><br></p>                                                                                       |
| `4xx`            | Client error    | <p><code>400</code> - Bad request<br><code>401</code> - Unauthorized<br><code>403</code> - Not Permitted<br><code>404</code> - Not Found</p> |
| `5xx`            | Server error    | <p><code>500</code> - Internal server error<br><code>502</code> - Bad gateway<br><code>504</code> - Gateway timeout</p>                      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://desarrollo.alberlome.com/conocimientos/que-es-una-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.