¿Qué es un API?

La primera fuente de datos con la que vamos a aprender a trabajar en Python son las API de datos basadas en la web. En este punto de control, le ofreceremos una introducción conceptual a las API y las solicitudes web. También utilizaremos una herramienta llamada Postman, que le permitirá inspeccionar y comprender mejor las solicitudes web. Luego, en el próximo punto de control, le mostraremos cómo realizar solicitudes a las API en Python.

[wp_ad_camp_1]

Antes de seguir con el artículo, te recomiendo revisar ¿Cómo obtener experiencia en ciencia de datos antes de tu primer trabajo?

Los datos se han convertido en una mercancía de gran valor. Un mecanismo para compartir datos de manera segura es el servicio web o la API web (abreviatura de interfaz de programación de aplicaciones). Los datos se exponen a través de una serie de funciones a las que se puede acceder mediante tecnologías web.

Las API pueden ser complejas. Las API varían desde una única función que proporciona un resultado simple hasta miles de funciones que ofrecen una variedad de resultados. Algunos aceptan parámetros y otros no. Algunos parámetros tienen restricciones en sus valores y otros no. Algunas API requieren autenticación especial. Algunos tienen restricciones sobre la cantidad de veces que se les puede llamar. Desafortunadamente, no hay una forma estándar de hacer nada de esto. Por lo tanto, para cada API que desee utilizar, debe profundizar en la documentación y descubrir su estructura y reglas particulares.

[wp_ad_camp_2]

Una forma popular de API es la API REST. Abreviatura de "transferencia de estado de representación", REST es una forma en que dos computadoras se comunican a través del protocolo de transferencia de hipertexto, o HTTP, la forma en que su navegador web interactúa con los servidores. Aprenderemos a manipular las API REST, por lo que es un buen término para saber. Pero no se obsesione demasiado con la ingeniería informática; nos centramos principalmente en recuperar datos.

Ejemplos

Antes de que podamos usar una API, necesitamos encontrarla. En muchos casos, la organización que quiere usar los datos ya sabe dónde se puede acceder a estos datos, pero en muchos otros casos, es posible que deba buscar datos. Aquí hay algunos buenos lugares para comenzar.

Data.gov

Data.gov es el sitio web de datos abiertos del gobierno de EE. UU. que enumera más de 300,000 conjuntos de datos que van desde la agricultura hasta la energía, desde la ciencia hasta la salud. Los datos se proporcionan en muchos formatos diferentes y de muchas agencias diferentes dentro del gobierno, por lo que es necesario realizar algunas búsquedas para encontrar datos relevantes.

Any API

Any API enumera y documenta más de 500 API públicas de una gran cantidad de organizaciones. Una vez más, estas API varían en lo que ofrecen, por lo que sería necesario realizar algunas búsquedas y excavaciones.

Endpoints

[wp_ad_camp_3]

Una API expone sus funciones como end points. Un end point está compuesto por un método HTTP y una ruta URL. Esto identifica de forma exclusiva alguna función en el servidor que devuelve datos. Algunos puntos finales aceptan parámetros, es decir, bits de datos que ayudan a la API a hacer su trabajo. Por ejemplo, si solicita datos meteorológicos de una API meteorológica, es posible que también deba proporcionar su ciudad o código postal como parámetro.

Para llamar al punto final necesita la URL completa. Las partes de una URL son:

El protocolo, el dominio y el puerto juntos se denominan URL base. La URL base identifica el servidor que aloja la API. La ruta es la ruta del end point que identifica la función específica que está llamando en este servidor. La cadena de consulta está compuesta por los parámetros necesarios para esta función de end point. En breve veremos algunos ejemplos.

Postman

Antes de comenzar a escribir código para obtener datos de una API, necesita saber qué ofrece la API. Esta información se encuentra principalmente en la documentación de la API. Pero incluso leer la documentación puede dejar algunas preguntas sin respuesta. Postman es una herramienta que le permite realizar llamadas HTTP a API web sin escribir código. Instalemos Postman, luego veamos la documentación de una API y hagamos algunas llamadas para ver qué sucede.

[wp_ad_camp_4]

Para comenzar con Postman, lo primero que debemos hacer es descargar la aplicación. Hay una extensión de Chrome y una herramienta de línea de comandos disponibles, pero utilizaremos la aplicación nativa. Vaya a https://www.getpostman.com/apps y descargue la versión adecuada para su sistema operativo. Una vez que finalice la descarga, abra la aplicación y manténgala abierta durante el resto de este punto de control. La aplicación debería abrir una ventana que se vea así:

Documentación API

Las API difieren mucho entre sí y no hay una forma estándar de documentarlas. Para hacer un uso adecuado de una API, debe leer detenidamente la documentación. Hay algunas cosas que debe saber sobre una API si planea usar una. Al leer la documentación, puede buscar lo siguiente:

• Cost - ¿Tienes que pagar para acceder a la API? ¿Existe un nivel gratuito y, de ser así, cuáles son sus limitaciones?
• Authentication - ¿Se requiere autenticación o está abierto? La mayoría de los conjuntos de datos interesantes requieren algún tipo de autenticación, lo que significa que tendrá que registrarse para obtener una cuenta para poder utilizar la API.
• API key - ¿Se requiere una clave API (generalmente va junto con la autenticación)? ¿Cómo se obtiene una clave API?
• Base URL - ¿Cuál es la URL base de la API?
• Responses -
  • ¿Qué opciones de formato de datos están disponibles? Muchos proporcionan formatos JSON, pero ese no es siempre el caso. XML también es bastante popular.
  • ¿Cuáles son los códigos de estado o códigos que puede devolver este punto final?
  • ¿Cuál es la estructura de los datos que devuelve este punto final?
  • ¿Qué limitaciones existen en los datos devueltos?
• Examples - ¿Hay ejemplos de llamadas típicas? ¿Hay ejemplos de código? ¿Están los ejemplos en un idioma o entorno relevante para usted?

• Endpoints - ¿Qué puntos finales están disponibles?
  • ¿Cuál es la URL del punto final?
  • ¿Qué método HTTP se usa para llamar a este punto final?
  • ¿Qué parámetros de ruta son necesarios?
  • ¿Qué parámetros de consulta son necesarios?
  • ¿Qué parámetros del cuerpo son necesarios?
  • ¿Qué parámetros son necesarios y cuáles son opcionales?
  • Para cada parámetro:
    • ¿Cuál es el tipo de datos del valor del parámetro?
    • ¿Cuál es el conjunto válido de valores permitidos para este parámetro?
    • Si el parámetro es opcional, ¿qué valor predeterminado utiliza la API?

La documentación de API varía considerablemente en términos de exhaustividad. Algunos documentos API no responderán todas las preguntas anteriores, mientras que otros responderán todas estas preguntas y más.

Veamos una API real.

Espero que este artículo esté siendo de tu agrado, aquí te comparto uno que lo complementa sobretodo en los negocios. Ciencia de Datos en los negocios.

La API GitHub

Para este ejemplo, consideraremos la API de GitHub. GitHub es una plataforma popular para administrar versiones, copias de seguridad y colaboración en proyectos de codificación.

[wp_ad_camp_5]

Visite la documentación de la API aquí: https://developer.github.com/v3/. Vamos a profundizar en esta documentación API principalmente como una forma de ilustrar cómo la documentación API puede ser útil. En realidad, aprender a usar la API de GitHub no es importante a menos que realmente planee usar esta API en sus propios proyectos más adelante.

Un vistazo rápido muestra que esta API es rica en términos de la cantidad de opciones disponibles y la profundidad de la documentación. Los documentos de la API de GitHub se hacen explícitamente con los desarrolladores en mente, con suficiente información para satisfacer una amplia variedad de casos de uso.

La primera característica a notar es que esta API está versionada explícitamente. La versión actual de la API es la versión 3, lo que implica que había dos versiones anteriores y existe la posibilidad de más versiones en el futuro. El número de versión aquí es importante ya que la API puede cambiar de una versión a otra, y su aplicación puede fallar si depende de una característica de la versión 3 pero solicita accidentalmente un punto final de la versión 4.

A continuación, esta documentación se organiza en dos secciones principales: Referencia y Guías. La sección de referencia proporciona información detallada exhaustiva sobre todo lo que esta API tiene para ofrecer. Es aquí donde encontrará las respuestas a la mayoría de las preguntas en nuestra lista de verificación. Incluye la lista completa de todos los end points API, parámetros, tipos, respuestas, excepciones, restricciones, límites y opciones.

Las guías, por otro lado, son más como tutoriales que explican cómo usar varias funciones de la API. Las guías son buenos lugares para encontrar ejemplos de cómo se puede usar la API, pero la información sobre los puntos finales no será tan detallada como la referencia.

Veamos cuántas de nuestras preguntas se responden explícitamente.

Cost: Github es una plataforma abierta, y aunque el precio no se trata explícitamente en esta página, el acceso a la API es gratuito. Consulte la sección sobre límites de velocidad para obtener más detalles.

Authentication: Aquí se usan diferentes niveles de autenticación para diferentes escenarios. Tenga en cuenta que OAuth2 es necesario para muchos puntos finales. Puede consultar las guías para ver algunas formas sugeridas de usar la autenticación.

Base URL: Hay una nota explícita sobre esto bajo el título ROOT End Point.

Data Format En esta documentación, esta información se encuentra bajo el título SCHEMA. La palabra "schema" se utiliza para significar la definición de formatos de datos. En alguna documentación, puede llamarse Modelo. Github acepta y responde con datos JSON.

Examples Eche un vistazo rápido a la página. Está lleno de llamadas de ejemplo. Encontrará que para cualquier punto final que vea, hay una extensa documentación y ejemplos de llamadas. Las llamadas en estos ejemplos se presentan como comandos curl. curl es una herramienta de línea de comandos para realizar solicitudes HTTP y puede ser muy útil para descubrir cómo funciona una API, pero generalmente es utilizada por desarrolladores de software dedicados. Afortunadamente, tenemos Postman, que nos permitirá explorar fácilmente algunos ejemplos.

Por ejemplo, en el punto final de búsqueda del repositorio (https://developer.github.com/v3/search/#search-repositories), el primer ejemplo en la página es este:

curl https://api.github.com/search/repositories?q=tetris+language:assembly&sort=stars&order=desc

Endpoints

La lista completa de end points se proporciona en el menú de navegación en el lado derecho de la página. Para determinar cuáles necesita, debe leerlas hasta encontrar las que necesita. Observe cómo se nombran los puntos finales para los objetos que sirven. Entonces, si está interesado en Gists, busque debajo del encabezado Gist, o si está interesado en Organizaciones, busque debajo del encabezado Organizaciones y así sucesivamente.

Continuemos mirando la página del punto final de búsqueda del repositorio. Este punto final tiene la URL / búsqueda / repositorios y es un punto final GET. Solo hay 3 parámetros:

Tenga en cuenta que solo se requiere q. Utilice Postman para probar lo que sucede cuando omite este parámetro requerido. Debería ver una respuesta como esta:

{
    "message": "Validation Failed",
    "errors": [
        {
            "resource": "Search",
            "field": "q",
            "code": "missing"
        }
    ],
    "documentation_url": "https://developer.github.com/v3/search"
}

Esa es una respuesta de error bastante descriptiva, lo que facilita el manejo de su código. Se pueden encontrar más detalles de las respuestas de error, en general, en la sección Errores del cliente de la documentación aquí: https://developer.github.com/v3/#client-errors.

Observe también que cada parámetro tiene un tipo de datos de cadena, y tanto la clasificación como el orden reciben listas específicas de valores válidos. También se proporcionan valores predeterminados para cada uno de estos parámetros opcionales.

GitHub tiene una sintaxis de búsqueda robusta que se puede utilizar a través de su interfaz web, así como en esta API. Algunos detalles se dan directamente en esta documentación de punto final, pero los detalles completos de cómo puede formatear el valor de q se pueden encontrar aquí: https://help.github.com/articles/searching-for-repositories/.

Use Postman para examinar algunas otras llamadas a la API de GitHub.