¿Cómo funciona una API?

Hasta el momento hablamos mucho de las APIs, pero puede ser difícil de imaginar su funcionamiento si nunca se trabajó con una. Pero es muy simple.

Al igual que un sitio web, una API tiene una URL. Generalmente, es un subdominio del dominio principal. Se indica también la versión de la API a utilizar, para evitar problemas de compatibilidades con otras versiones disponibles. Por ejemplo:

https://api.myperfit.com/v2

La mayoría de los recursos dependen de una cuenta específica, la cual se indica a continuación:

https://api.myperfit.com/v2/micuenta

Y luego el tipo de objeto que queremos obtener. Por ejemplo, tus contactos:

https://api.myperfit.com/v2/micuenta/contacts

O tus listas:

https://api.myperfit.com/v2/micuenta/lists

Y mucho más.

A esas URL podemos hacerles diferentes tipos de llamadas, o métodos HTTP:

  • GET para leer datos de los elementos
  • POST para crear un elemento nuevo
  • PUT para modificar datos de un elemento, indicando su ID
  • DELETE para eliminar un elemento, indicando su ID

¿En qué formato se recibe la información?

La respuesta a cada una de estas llamadas será un conjunto de datos en formato JSON. Este tipo de formato permite estructurar información a partir de texto plano. Por ejemplo, si pedimos los datos de un contacto veríamos algo así:

{
    "href": "/micuenta/contacts/1",
    "success": true,
    "data": {
        "id": 1,
        "email": "juanperez@ejemplo.com",
        "firstName": "Juan",
        "lastName": "Pérez"
    }
}

Como ven, es sólo texto: utiliza llaves, comillas y comas para separar cada porción de datos.

Lo mejor es que el formato JSON puede ser comprendido y utilizado por cualquier lenguaje de programación: PHP, Java, .NET, Javascript, Phyton y más. Por eso, JSON se ha convertido en el lenguaje por defecto de todos las APIs en la actualidad.

Y esa informacion se puede usar como quieras, quizás armando un HTML con un listado de contactos.

¿Quiénes pueden utilizar la API?

La API puede ser usada por cualquier usuario perteneciente a la cuenta. Las restricciones y permisos que tiene cada usuario de la aplicación, configurados en la sección Ajustes, se respetan también en la API. Por eso, quienes no tengan acceso a la edición de listas (o cualquier otro módulo), tampoco podrán hacerlo usando la API.

¿Como se identifican los usuarios?

Existen 2 formas de identificar a un usuario en la API:

  • A través de un parametro especial llamado token. El token se obtiene haciendo un llamado al recurso /login indicando el nombre de usuario y contraseña. Los token expiran luego de un tiempo de inactividad, y es necesario generar uno nuevo.
  • A través del API key asociado al usuario. Esta es la forma preferida de uso de la API ya que no requiere un llamado a /login y no es necesario almacenar un token de autenticación.

Para saber más sobre cómo obtener un token y comenzar a utilizar la API, visita la sección Autenticación .