GitHub come applicazione web è un'entità enorme e complessa. Pensa a tutti i repository, gli utenti, le filiali, i commit, i commenti, le chiavi SSH e le app di terze parti che ne fanno parte. Inoltre, ci sono molti modi per comunicare con esso. Ci sono app desktop per GitHub, estensioni per il codice Visual Studio ed Editor Atom, App Git CLI, Android e iOS per citarne alcuni.

Le persone di GitHub, e gli sviluppatori di terze parti, non possono gestire tutta questa complessità senza un'interfaccia comune. Questa interfaccia comune è ciò che chiamiamo API GitHub. Ogni utilità GitHub come una CLI, l'interfaccia utente Web, ecc. Utilizza questa interfaccia comune per gestire le risorse (risorse come entità come repository, chiavi SSH, ecc.

In questo tutorial impareremo alcune basi di come si interfaccia con un'API usando l'API V3 e Python3. L'ultima V4 dell'API GitHub richiede di conoscere GraphQL che si traduce in una curva di apprendimento più ripida. Quindi mi atterrò alla semplice versione tre che è ancora attiva e piuttosto popolare.

Come parlare con un'API web

Le API Web sono ciò che consente di utilizzare tutti i servizi offerti da un'app Web, come GitHub, utilizzando a livello di linguaggio di tua scelta. Ad esempio, useremo Python per il nostro caso d'uso, qui. Tecnicamente, puoi fare tutto ciò che fai su GitHub usando l'API ma ci limiteremo a leggere solo le informazioni accessibili al pubblico.

Il tuo programma Python parlerà con un'API allo stesso modo del tuo browser parla di un sito Web. Vale a dire, principalmente tramite richieste HTTPS. Queste richieste conterranno diverse "parti", a partire dal metodo della richiesta [get, post, put, elimina], URL stesso, una stringa di query, un'intestazione HTTP e un corpo o un carico utile. La maggior parte di questi sono opzionali. Dovremo tuttavia fornire un metodo di richiesta e l'URL a cui stiamo facendo la richiesta.

Cosa sono e come sono rappresentati in una richiesta HTTPS è qualcosa che vedremo lentamente quando inizieremo a scrivere script di Python per interagire con GitHub.

Un esempio

L'aggiunta di tasti SSH a un server appena creato è sempre un processo goffo. Scriviamo uno script Python che recupererà le chiavi SSH pubbliche da GitHub e lo aggiungerà al file Authorized_keys su qualsiasi server Linux o Unix in cui esegui questo script. Se non sai come generare o utilizzare le chiavi SSH, ecco un eccellente articolo su come fare esattamente questo. Suppongo che tu abbia creato e aggiunto le tue chiavi SSH pubbliche sul tuo account GitHub.

Un'implementazione Python molto semplice e ingenua per raggiungere il compito che abbiamo descritto sopra è mostrata di seguito:

richieste di importazione
Import OS
# Ottenere l'input dell'utente
unix_user = input ("Immettere il nome utente UNIX:")
github_user = input ("Inserisci il nome utente GitHub:")
# Assicurarsi .La directory SSH esiste e l'apertura del file Authorized_keys
ssh_dir = '/home/'+unix_user+'/.ssh/'
se non OS.sentiero.esiste (ssh_dir):
sistema operativo.Makedirs (ssh_dir)
autorized_keys_file = open (ssh_dir+'autorized_keys', 'a')
# Invio di una richiesta all'API GIHUB e memorizzazione della risposta in una variabile denominata'response '
api_root = "https: // API.github.com "
request_header = 'accetta': 'applicazione/vnd.github.v3+json '
risposta = richieste.get (api_root+'/utenti/'+github_user+'/keys', headers = request_header)
## Elaborazione delle chiavi di risposta e aggiunta al file Authorized_keys
per me in risposta.json ():
AUTORIZE_KEYS_FILE.Scrivi (i ['key']+'\ n')

Ignoriamo la gestione dei file Python e i dettagli vari e guardiamo rigorosamente la richiesta e la risposta. Per prima cosa abbiamo importato le richieste di importazione del modulo richieste Questa libreria ci consente di effettuare le chiamate API molto facilmente. Questa biblioteca è anche uno dei migliori esempi di un progetto open source fatto bene. Ecco il sito ufficiale nel caso in cui desideri dare un'occhiata più da vicino ai documenti.

Successivamente impostiamo una variabile api_root.

api_root = "https: // API.github.com "

Questa è la sottostringa comune in tutti gli URL a cui effettueremo chiamate API. Quindi invece di digitare “https: // API.github.com "Ogni volta che dobbiamo accedere a https: // API.github.com/utenti o https: // API.github.com/ utenti/ scriviamo api_root+'/utenti/' O api_root+'/utenti/', Come mostrato nello snippet del codice.

Successivamente, impostiamo l'intestazione nella nostra richiesta HTTPS, indicando che le risposte sono pensate per l'API versione 3 e dovrebbero essere formattate JSON. GitHub rispetterebbe queste informazioni di intestazione.

Ottieni una richiesta

Quindi ora che abbiamo il nostro URL e un'informazione (opzionale) di intestazione memorizzate in diverse variabili, è tempo di fare la richiesta.

risposta = richieste.get (api_root+'/utenti/'+github_user+'/keys', headers = request_header)

La richiesta è di tipo "get" perché stiamo leggendo le informazioni disponibili pubblicamente da GitHub. Se stavi scrivendo qualcosa sotto il tuo account utente GitHub, useresti Post. Allo stesso modo, altri metodi sono pensati per altre funzioni come Elimte è per la cancellazione di risorse come i repository.

Endpoint API

L'endpoint API per cui stiamo raggiungendo è:

https: // API.github.com/utenti//chiavi

Ogni risorsa GitHub ha il suo endpoint API. Le tue richieste per ottenere, pulire, eliminare, ecc. Vengono quindi fatte contro l'endpoint che hai fornito. A seconda del livello di accesso che hai, GitHub ti permetterà di seguire quella richiesta o negarlo.

La maggior parte delle organizzazioni e degli utenti su GitHub ha impostato un'enorme quantità di informazioni leggibili e pubbliche. Ad esempio, il mio account utente GitHub ha un paio di repository pubblici e chiavi SSH pubbliche che chiunque può leggere l'accesso (anche senza un account utente GitHub). Se vuoi avere un controllo più a grana del tuo account personale, puoi generare un "token di accesso personale" per leggere e scrivere informazioni privilegiate archiviate nel tuo account GitHub personale. Se stai scrivendo un'applicazione di terze parti, intesa per essere utilizzata da utenti diversi da te, allora un token OAuth di detto utente è ciò di cui la tua applicazione richiederebbe.

Ma come puoi vedere, è possibile accedere molte informazioni utili senza creare alcun token.

Risposta

La risposta viene restituita dal server API GitHub ed è archiviata nella variabile denominata risposta. L'intera risposta potrebbe essere letta in diversi modi come documentato qui. Abbiamo chiesto esplicitamente il contenuto di tipo JSON da GitHub, quindi elaboreremo la richiesta, come se fosse JSON. Per fare ciò, chiamiamo il metodo JSON () dal modulo richieste che lo decodificherà in oggetti nativi di Python come dizionari ed elenchi.

Puoi vedere le chiavi che vengono aggiunte al file Authorized_keys in questo per loop:

per me in risposta.json ():
AUTORIZE_KEYS_FILE.Scrivi (i ['key']+'\ n')

Se stampano la risposta.Oggetto JSON (), noterai che si tratta di un elenco di Python con i dizionari di Python come membri. Ogni dizionario ha una chiave denominata "chiave" con la chiave SSH pubblica come valore a quella chiave. Quindi puoi aggiungere questi valori uno per uno al tuo file autorizzato. E ora puoi facilmente SSH nel tuo server da qualsiasi computer che ha qualcuno delle chiavi SSH private corrispondenti a una delle chiavi pubbliche che abbiamo appena aggiunto.

Esplorare ulteriormente

Un sacco di lavoro con le API comporta un'attenta ispezione della documentazione API stessa più che scrivere righe di codice. In caso di GitHub, la documentazione è una delle migliori del settore. Ma leggere su documenti API e fare chiamate API usando Python è piuttosto poco interessante come attività autonoma.

Prima di andare oltre, ti consiglierei di trovare un'attività che vorresti eseguire usando Python sul tuo account GitHub. Quindi prova ad implementarlo leggendo solo le documentazioni ufficiali fornite da Python, le sue biblioteche dipendenti e GitHub. Questo ti aiuterà anche ad adottare una mentalità più sana in cui capisci cosa sta succedendo all'interno del tuo codice e miglioralo gradualmente nel tempo.