Cómo utilizar la API de GitHub en Python: una guía completa

La API de GitHub abre un apasionante mundo de posibilidades para automatizar flujos de trabajo, integrarse con GitHub, gestionar proyectos y analizar datos. Como desarrolladores de Python, podemos aprovechar al máximo la API para aumentar nuestra productividad y crear herramientas útiles.

En esta guía completa paso a paso, aprenderá cómo utilizar la API de GitHub usando Python.

¿Por qué utilizar la API de GitHub con Python?

Antes de pasar al código, veamos por qué usar la API de GitHub con Python es tan poderoso:

Automatizar los flujos de trabajo – Elimine tareas repetitivas escribiendo scripts para crear problemas, abrir y fusionar relaciones públicas, publicar archivos binarios, etc.
Mejore la productividad – Integre herramientas personalizadas en su entorno de desarrollo para mejorar los flujos de trabajo.
Gestionar proyectos – Administre programáticamente problemas, etiquetas e hitos en todos los repositorios.
Analizar datos – Extraiga métricas e información interesantes de más de 96 millones de repositorios.
Integrar y ampliar GitHub – ¡Cree aplicaciones web personalizadas, visualizaciones, herramientas CLI, bots y más!

La API abre muchas formas creativas de aumentar la productividad y crear excelentes herramientas y experiencias para desarrolladores.

Descripción general de la API de GitHub

La API de GitHub proporciona puntos finales RESTful para acceder a datos y servicios de GitHub. Puede:

Gestione repositorios, aspectos esenciales, incidencias y solicitudes de extracción.
Interactuar con datos de Git: confirmaciones, ramas, etiquetas
Recuperar perfiles de usuarios, organizaciones, equipos.
Código de búsqueda, problemas, repositorios, usuarios.
Acceda a metadatos, problemas, relaciones públicas, archivos y confirmaciones.
Analizar tendencias de la comunidad, bifurcaciones de proyectos.

Y mucho más!

La API utiliza JSON para serializar datos y utiliza OAuth para la autenticación. Todas las solicitudes deben realizarse a través de HTTPS.

Para utilizar la API, simplemente:

Crea una cuenta de GitHub
Generar un token de acceso personal para autentificación
Realizar solicitudes de API y manejar respuestas

¡Ahora veamos esto en acción con ejemplos de Python!

Realizar solicitudes de API de GitHub

pitón requests La biblioteca facilita la interacción con las API web. Busquemos algunos datos de usuario de GitHub:

import requests

username = "defunkt"
response = requests.get(f"https://api.github.com/users/{username}")

print(response.json())

Esto imprime información como:

{
  "login": "defunkt",
  "id": 2,
  "node_id": "MDQ6VXNlcjI=",
  "avatar_url": "https://avatars.githubusercontent.com/u/2?v=4",
  "gravatar_id": "",
  "url": "https://api.github.com/users/defunkt",
  "html_url": "https://github.com/defunkt",

  //...
}

Podemos acceder a cualquier ruta API no autenticada de esta manera. Para acceder a datos privados, debemos pasar un token de autenticación.

Crear un token de acceso personal de GitHub

Para generar un token:

Ve a Configuración > Configuración de desarrollador > Tokens de acceso personal
Haga Clic en Generar nuevo token
Dale una descripción como "Mi script Python".
Seleccione los ámbitos/permisos que desee
Haga Clic en Generar token

Asegúrate de copiar el token: ¡no podrás recuperarlo más tarde!

Los alcances comunes incluyen:

repo – Acceder a repositorios privados
admin:org – Gestionar organizaciones
notifications – Acceder a notificaciones
user – Acceso de lectura/escritura a la información del perfil.

Usemos nuestro token para crear un nuevo repositorio:

import requests

token = "ghp_123abcMyToken"

data = {"name": "My New Repo"}

response = requests.post(
  "https://api.github.com/user/repos", 
  json=data,
  headers={"Authorization": f"token {token}"}
)

print(response.status_code) # 201 = Success!

El token nos autentica para crear repositorios privados.

También puedes usar Aplicaciones GitHub que tienen acceso limitado y no caducan como los tokens de usuario. Las aplicaciones deben ser instaladas por un usuario/organización para obtener acceso.

Trabajar con repositorios de GitHub

Una parte importante de la API implica la gestión de repositorios. Repasemos algunas tareas comunes del repositorio.

Obtener un repositorio

Para obtener los metadatos de un repositorio:

response = requests.get("https://api.github.com/repos/pandas-dev/pandas")
repo_info = response.json()

print(repo_info[‘description‘]) 
# Powerful data structures for data analysis, time series, statistics

¡Podemos acceder a información como descripciones, estrellas, clones, contribuyentes, idiomas, lanzamientos, confirmaciones y mucho más!

Listar repositorios

Para enumerar repositorios para un usuario u organización:

repos_url = "https://api.github.com/users/octocat/repos"
repos = requests.get(repos_url).json()

for repo in repos:
  print(repo[‘name‘]) # Prints names of each repo

Crear un repositorio

También podemos crear nuevos repositorios:

data = {
  "name": "My New Repo",
  "description": "This is my cool new repo",
  "private": False
}

response = requests.post(
  "https://api.github.com/user/repos", 
  json=data,
  headers={"Authorization": "token {token}"}
)

Eliminar un repositorio

Para eliminar un repositorio:

requests.delete(‘https://api.github.com/repos/octocat/Hello-World‘, 
                headers={"Authorization": "token {token}"})

Esto le brinda control total sobre la administración programática de sus repositorios.

Nota: Todas las solicitudes de API deben realizarse mediante HTTPS por motivos de seguridad.

Trabajar con incidencias en repositorios

La API de Issues permite gestionar problemas y solicitudes de extracción. Puede:

Listar/crear/editar/cerrar/reabrir problemas
Bloquear conversaciones, fusionar relaciones públicas
Enviar y editar comentarios
Agregar etiquetas, asignados, hitos

Por ejemplo, para obtener incidencias de un repositorio:

response = requests.get(‘https://api.github.com/repos/octocat/hello-world/issues‘)
issues = response.json()

for issue in issues:
  print(issue[‘title‘]) # Prints each issue title

Esto le permite integrar la gestión de problemas en herramientas y flujos de trabajo externos.

Trabajar con datos de Git

La API de Git Data proporciona puntos finales para interactuar directamente con los repositorios de Git. Puede:

Administrar ramas y etiquetas
Leer/escribir datos de blobs
Recuperar confirmaciones, referencias, árboles.
Comparar confirmaciones, referencias, archivos

Por ejemplo, para obtener confirmaciones de un repositorio:

commits_url = "https://api.github.com/repos/pandas-dev/pandas/commits"
commits = requests.get(commits_url).json()

for commit in commits:
  print(commit[‘sha‘]) # Print commit SHAs
  print(commit[‘commit‘][‘message‘]) # Print messages

Esto proporciona acceso completo para administrar mediante programación repositorios Git.

Búsqueda de repositorios y código

La API de búsqueda de GitHub permite realizar consultas sobre casi cualquier cosa en los más de 96 millones de repositorios públicos.

Por ejemplo, para buscar proyectos de Python relacionados con la ciencia de datos:

import requests

query = "language:python data science in:readme"
response = requests.get("https://api.github.com/search/repositories", 
                        params={"q": query})

results = response.json()[‘items‘]
for result in results:
  print(result[‘name‘]) # Prints names of matching repos

La sintaxis de la consulta de búsqueda admite operadores booleanos, filtros, selección de contexto y más para crear búsquedas específicas.

Algunos ejemplos:

org:facebook language:python stars:>5000 – Repositorios de Python en la organización de Facebook con más de 5k estrellas
filename:requirements.txt django – Repositorios con requisitos.txt que contienen Django
user:defunkt location:san francisco – Encuentra los repositorios de defunkt si la ubicación es SF

La API de búsqueda abre muchas formas creativas de extraer conjuntos de datos interesantes y conocimientos de los datos abiertos de GitHub.

Usando la API GraphQL de GitHub

Además de la API REST, GitHub proporciona una API GraphQL para consultas más flexibles.

GraphQL le permite especificar con precisión los datos que desea en estructuras JSON anidadas. Puede consultar varias entidades vinculadas en una sola solicitud.

Por ejemplo, aquí consultamos los datos del perfil de un usuario así como los nombres de sus repositorios:

import requests 

query = """
query {
  user(login:"defunkt") {
    name
    repositories(first:10) {
      nodes { 
        name 
      }
    }
  }
}
"""

response = requests.post(‘https://api.github.com/graphql‘, json={‘query‘: query})
print(response.json())

Esto permite dar forma a la respuesta exacta que necesita. El Explorador GraphQL ayuda a crear consultas de forma interactiva.

Integración de la API de GitHub en aplicaciones

Ahora que conoce los conceptos básicos, veamos cómo crear aplicaciones con la API de GitHub.

Autorización de la aplicación OAuth

Para aplicaciones web, utilice GitHub OAuth para autorización en lugar de tokens codificados. Esto permite a los usuarios revocar el acceso.

Registre una nueva aplicación OAuth
Utilice el ID de cliente y el secreto para obtener autorización
Redirigir a los usuarios para que soliciten acceso a GitHub

Ahora su aplicación puede realizar llamadas API en nombre de los usuarios.

Realizar solicitudes autenticadas

Una vez autorizado, realiza llamadas con el token de acceso:

access_token = "abc123xxddff" # OAuth token 

response = requests.get(
  "https://api.github.com/user/repos",
  headers={"Authorization": f"token {access_token}"}
)

print(response.json()) # Print user‘s private repos

Esto le permite acceder a datos privados según los permisos del usuario.

Limitación de la velocidad

La API de GitHub tiene límites de tasa de solicitudes. Supervise el estado de su aplicación:

response = requests.get("https://api.github.com/users/octocat") 

print(response.headers[‘X-RateLimit-Limit‘]) # 5000
print(response.headers[‘X-RateLimit-Remaining‘]) # 4999

Distribuya las solicitudes a lo largo del tiempo y almacene en caché los datos para evitar límites.

Manejar los errores con gracia

Siempre verifique los códigos de estado y maneje los errores adecuadamente:

response = requests.get(‘https://api.github.com/invalid/url‘)

if response.status_code == 404:
  print("Resource not found!") 
elif response.status_code == 403:
  print("You do not have access!")
else:
  print("An error occurred.")

Esto garantiza que su aplicación se mantenga estable en producción.

Si sigue las mejores prácticas de API, puede crear integraciones y herramientas sólidas para desarrolladores.

Creación de una aplicación de panel de GitHub

Reunamos lo que aprendimos al crear una aplicación web para ver su perfil de GitHub y repositorios usando Flask:

# app.py

from flask import Flask
import requests
from github import Github # pyGithub library

app = Flask(__name__)

@app.route("/")
def dashboard():
  # Use access token for API requests
  github = Github("access_token123xxdd")

  # Fetch user profile info
  user = github.get_user()

  # Fetch list of repos
  repos = user.get_repos() 

  # Pass info to template
  return render_template("dashboard.html", user=user, repos=repos)

if __name__ == "__main__":
  app.run(debug=True)

Usamos pyGithub para simplificar algunas interacciones API. La página de inicio mostrará el dashboard.html modelo:

<!-- dashboard.html -->

<h3>GitHub Dashboard for {{user.name}}</h3>

<img src="{{user.avatar_url}}" style="width:64px">

<h4>Your Repositories</h4>

<ul>
  {% for repo in repos %}
  <li>{{repo.name}}</li>
  {% endfor %}
</ul>

¡Esto muestra cómo se puede crear una aplicación para mostrar datos de GitHub para un usuario que haya iniciado sesión!

Las posibilidades son infinitas para integrar la API en sus propias aplicaciones y herramientas.

Mejores prácticas al utilizar la API de GitHub

Estas son algunas de las mejores prácticas para garantizar que sus aplicaciones que utilizan la API de GitHub sean eficientes, seguras y sólidas:

Autenticación – Utilice tokens u OAuth, evite enviar nombres de usuario/contraseñas sin formato.
HTTPS – Utilice siempre puntos finales HTTPS para proteger los datos.
Limitación de la velocidad – Distribuya las solicitudes y almacene en caché los datos para evitar límites.
Paginación – Utilice parámetros de página para iterar a través de conjuntos de resultados.
Manejo de errores – Maneje los errores 4xx y 5xx con elegancia.
Pruebas – Pruebe minuciosamente las llamadas API, utilice burlas para las iteraciones.
Documentación – Lea los documentos con atención, proporcionan ejemplos de código para cada punto final.

Seguir las mejores prácticas de API evita errores evitables y garantiza aplicaciones confiables.

Otras características de la API de GitHub para explorar

Sólo hemos arañado la superficie de lo que es posible con la API de GitHub. Aquí hay algunas otras características interesantes para revisar:

API de acciones de GitHub – Automatizar flujos de trabajo activando acciones con la API
Páginas de GitHub – Administrar sitios de páginas mediante programación
esencias – Administrar fragmentos de código, configuraciones y plantillas
Organizaciones – Administrar equipos de organización, miembros y permisos
Base de datos Git – Acceda directamente a datos de objetos de Git, como blobs y árboles.
API del mercado GitHub – Administrar aplicaciones enumeradas en GitHub Marketplace
API de debates de GitHub – Crear foros comunitarios e integraciones de preguntas y respuestas.

Las capacidades de la API se expanden a medida que GitHub agrega nuevas funciones, así que esté atento a los nuevos puntos finales.

Compare la API de GitHub con alternativas

Para los desarrolladores que trabajan con otras plataformas, ¿cómo se compara la API de GitHub con competidores como GitLab, BitBucket, Azure DevOps, etc.?

En general, las capacidades API de GitHub se destacan en términos de:

Adopción – Con diferencia, la base de usuarios y la comunidad más grandes
Documentación – Documentos extremadamente completos con ejemplos.
DESCANSO + GraphQL – Flexibilidad de los puntos finales REST y GraphQL
Capacidades de búsqueda – Potente búsqueda indexada en todos los datos públicos.
Ecosistema – Enorme ecosistema de aplicaciones, herramientas e integraciones.
Análisis de código – Capacidades de escaneo de código, linting y análisis de calidad.

GitHub claramente lidera en funcionalidad API gracias a su escala y años de desarrollo. Otros proveedores como GitLab y BitBucket están ampliando las capacidades de API para competir. Pero por ahora GitHub sigue siendo la API con más funciones para interactuar mediante programación con repositorios de Git.

Próximos pasos y recursos

Espero que esta guía proporcione una descripción general completa de cómo usar la API de GitHub con Python.

A continuación se detallan algunos de los próximos pasos y recursos para seguir aprendiendo:

Profundice en los documentos: Documentos para desarrolladores
Vea vídeos de API: Laboratorio de aprendizaje de GitHub
Descubra aplicaciones creadas con la API: Marketplace de GitHub
Obtenga más información sobre OAuth: Documentos de la aplicación OAuth
Consulte bibliotecas como PyGithub y urllib3 para simplificar el uso de API
Considere respuestas burlonas para probar la interacción API
Explore herramientas asociadas como GitHub CLI y GitHub Actions

La API de GitHub abre todo un mundo de posibilidades para crear herramientas de desarrollo, automatizar flujos de trabajo, gestionar proyectos y analizar datos. ¡Espero que te sientas inspirado para crear algo valioso para la comunidad!

¡Feliz codificación!