Github som webapplikasjon er en enorm og sammensatt enhet. Tenk på alle depoter, brukere, filialer, forpliktelser, kommentarer, SSH -nøkler og tredjepartsapper som er en del av det. Dessuten er det flere måter å kommunisere med det. Det er stasjonære apper for github, utvidelser for Visual Studio Code og Atom Editor, Git CLI, Android og iOS -apper for å nevne noen.

Personer på Github og tredjepartsutviklere kan umulig håndtere all denne kompleksiteten uten et felles grensesnitt. Dette vanlige grensesnittet er det vi kaller GitHub API. Hvert GitHub -verktøy som en CLI, Web UI, osv.

I denne opplæringen lærer vi noen grunnleggende om hvordan ett grensesnitt med en API ved hjelp av GitHub API V3 og Python3. Den siste V4 av GitHub API krever at du lærer om GraphQL som resulterer i brattere læringskurve. Så jeg vil holde meg til bare versjon tre som fremdeles er aktiv og ganske populær.

Hvordan snakke med et web -api

Web APIer er det som gjør at du kan bruke alle tjenestene som tilbys av en webapp, som Github, programmatisk ved å bruke språk etter eget valg. For eksempel skal vi bruke Python til brukssaken vår, her. Teknisk sett kan du gjøre alt du gjør på GitHub ved å bruke API, men vi vil begrense oss til bare å lese den offentlig tilgjengelige informasjonen.

Python -programmet ditt vil snakke med en API akkurat på samme måte som nettleseren din snakker med et nettsted. Det vil si, mest via HTTPS -forespørsler. Disse forespørslene vil inneholde forskjellige 'deler', med start fra metoden for forespørselen [Get, Post, Put, Delete], selve URL -en, en spørringsstreng, en HTTP -overskrift og en kropp eller en nyttelast. De fleste av disse er valgfrie. Vi må imidlertid oppgi en forespørselsmetode og URL som vi ber om forespørselen.

Hva disse er og hvordan de er representert i en HTTPS -forespørsel er noe vi vil se sakte når vi begynner å skrive Python -skript for å samhandle med GitHub.

Et eksempel

Å legge SSH -nøkler til en nyopprettet server er alltid en klønete prosess. La oss skrive et Python -skript som vil hente de offentlige SSH -nøklene fra Github og legge det til i Autorized_keys -filen på hvilken som helst Linux- eller Unix -server der du kjører dette skriptet. Hvis du ikke vet hvordan du skal generere eller bruke SSH -nøkler, er her en utmerket artikkel om hvordan du gjør akkurat det. Jeg vil anta at du har opprettet og lagt til dine egne offentlige SSH -nøkler til GitHub -kontoen din.

En veldig enkel og naiv Python -implementering for å oppnå oppgaven vi beskrev ovenfor er som vist nedenfor:

Importer forespørsler
Importer OS
# Få brukerinngang
UNIX_USER = input ("Gå inn i UNIX -brukernavnet:")
github_user = input ("Skriv inn ditt github brukernavn:")
# Forsikre seg om .SSH -katalogen eksisterer og åpner autorisert_keysfil
ssh_dir = '/home/'+unix_user+'/.ssh/'
Hvis ikke OS.sti.eksisterer (ssh_dir):
OS.makedirs (ssh_dir)
autorisert_keys_file = åpen (ssh_dir+'autoriserte_keys', 'a')
# Sende en forespørsel til Gihub API og lagrer responsen i en variabel kalt'Response '
api_root = "https: // api.github.com "
Request_Header = 'Accept': 'Application/VND.github.v3+json '
Svar = forespørsler.få (api_root+'/brukere/'+github_user+'/nøkler', headers = request_header)
## Behandling av responsen og vedtekter til autorisert_keys -fil
for jeg som svar.json ():
autorisert_keys_file.Skriv (i ['Key']+'\ n')

La oss ignorere Python -filhåndtering og diverse detaljer og se strengt på forespørselen og svaret. Først importerte vi forespørselsmodulens importforespørsler Dette biblioteket lar oss ringe API -samtaler veldig enkelt. Dette biblioteket er også et av de beste eksemplene på et open source -prosjekt gjort riktig. Her er det offisielle nettstedet i tilfelle du vil se nærmere på dokumentene.

Neste setter vi en variabel api_root.

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

Dette er den vanlige substringen i alle nettadressene som vi skal ringe API -samtaler. Så i stedet for å skrive “https: // API.github.com ”hver gang vi trenger å få tilgang til https: // API.github.com/brukere eller https: // API.github.com/ brukere/ vi skriver bare api_root+'/brukere/' eller api_root+'/brukere/', Som vist i kodebiten.

Deretter satte vi overskriften i HTTPS -forespørselen vår, noe som indikerer at svarene er ment for versjon 3 API og bør være JSON -formatert. Github ville respektere denne overskriften informasjon.

Få forespørsel

Så nå som vi har vår URL og (en valgfri) informasjonsinformasjon som er lagret i forskjellige variabler, er det på tide å komme med forespørselen.

Svar = forespørsler.få (api_root+'/brukere/'+github_user+'/nøkler', headers = request_header)

Forespørselen er av typen 'get' fordi vi leser offentlig tilgjengelig informasjon fra GitHub. Hvis du skrev noe under GitHub -brukerkontoen din, ville du brukt innlegg. Tilsvarende er andre metoder ment for andre funksjoner som sletting er for sletting av ressurser som depoter.

API endepunkt

API -endepunktet som vi når ut for er:

https: // api.github.com/brukere//nøkler

Hver github -ressurs har sitt eget API -endepunkt. Dine forespørsler om Get, Put, Delete osv. Blir deretter laget mot sluttpunktet du leverte. Avhengig av tilgangsnivået du har, vil Github da enten tillate deg å gå gjennom med den forespørselen eller nekte den.

De fleste organisasjoner og brukere på GitHub setter en enorm mengde informasjon lesbar og offentlig. For eksempel har min GitHub -brukerkonto et par offentlige depoter og offentlige SSH -nøkler som hvem som helst kan lese tilgang (selv uten en GitHub -brukerkonto). Hvis du vil ha en mer finkornet kontroll over din personlige konto, kan du generere en "personlig tilgangstoken" for å lese og skrive privilegert informasjon som er lagret i din personlige GitHub-konto. Hvis du skriver en tredjeparts applikasjon, ment å bli brukt av andre brukere enn deg, er en OAuth -symbol på nevnte bruker det applikasjonen din vil kreve.

Men som du kan se, kan du få tilgang til mye nyttig informasjon uten å lage noe token.

Respons

Responsen returneres fra GitHub API -serveren og lagres i variabelen som er navngitt respons. Hele responsen kan leses på flere måter som dokumentert her. Vi ba eksplisitt om innhold av JSON -type fra GitHub, så vi vil behandle forespørselen, som om det er JSON. For å gjøre dette kaller vi JSON () -metoden fra forespørselsmodulen som vil avkode den i Python innfødte objekter som ordbøker og lister.

Du kan se nøklene som blir lagt til den autoriserte_key -filen i denne for loop:

for jeg som svar.json ():
autorisert_keys_file.Skriv (i ['Key']+'\ n')

Hvis du skriver ut svaret.JSON () Objekt, vil du merke at det er en Python -liste med Python Dictionaries som medlemmer. Hver ordbok har en nøkkel som heter 'Key' med din offentlige SSH -nøkkel som verdi for den nøkkelen. Så du kan legge til disse verdiene en etter en til din autoriserte_keys -fil. Og nå kan du enkelt SSH til serveren din fra hvilken som helst datamaskin som har noen av de private SSH -nøklene som tilsvarer en av de offentlige nøklene vi nettopp legger.

Utforske videre

Mye arbeid med APIer innebærer nøye inspeksjon av selve API -dokumentasjonen mer enn å skrive kodelinjer. I tilfelle av Github er dokumentasjonen en av de fineste i bransjen. Men å lese opp API -dokumenter og ringe API -samtaler ved hjelp av Python er ganske uinteressant som en frittstående aktivitet.

Før du går lenger, vil jeg anbefale deg å komme med en oppgave som du vil utføre ved hjelp av Python på GitHub -kontoen din. Prøv deretter å implementere det ved å lese bare de offisielle dokumentene levert av Python, dens avhengige biblioteker og github. Dette vil også hjelpe deg å ta i bruk et sunnere tankesett der du forstår hva som skjer i koden din og forbedrer den gradvis over tid.