Phenquestions
TL;DR-versie
In een van de vorige berichten hebben we in het kort besproken hoe het is om de GitHub API v3 te gebruiken. Deze versie is ontworpen om te worden gekoppeld zoals elke andere REST API. Er zijn eindpunten voor elke bron die u moet openen en/of wijzigen. Er zijn eindpunten voor elke gebruiker, elke organisatie, elke repository enzovoort and. Elke gebruiker heeft bijvoorbeeld zijn/haar API-eindpunt op https://api.github.com/gebruikers/
GitHub API v4 daarentegen gebruikt GraphQL waarbij de QL staat voor Query Language. GraphQL is een nieuwe manier om uw API's te ontwerpen. Net zoals er veel webservices worden aangeboden als REST-API's, niet alleen degene die worden aangeboden door GitHub, zijn er veel webservices waarmee u via GraphQL ermee kunt communiceren.
Het grootste verschil dat u zult opmerken tussen GraphQL en REST API is dat GraphQL kan werken vanaf een enkel API-eindpunt. In het geval van GitHub API v4 is dit eindpunt https://api.github.com/graphql en dat is dat. U hoeft zich geen zorgen te maken over het toevoegen van lange tekenreeksen aan het einde van een root-URI of een queryreeksparameter op te geven voor extra informatie. Je stuurt eenvoudig een JSON-achtig argument naar deze API, waarbij je alleen vraagt om de dingen die je nodig hebt, en je krijgt een JSON-payload terug met exact dezelfde informatie die je hebt aangevraagd. U hoeft zich niet bezig te houden met het uitfilteren van ongewenste informatie, of last te hebben van prestatieoverhead vanwege grote reacties.
Wat is REST API?
Welnu, REST staat voor Representational State Transfer en API staat voor Application Programming Interface. Een REST API, of een 'RESTful' API, is de belangrijkste ontwerpfilosofie geworden achter de meeste moderne client-server-apps. Het idee komt voort uit de noodzaak om verschillende componenten van een applicatie te scheiden, zoals de client-side UI en server-side logica.
Dus de sessie tussen een client en een server is meestal stateless. Zodra de webpagina en gerelateerde scripts zijn geladen, kunt u ermee doorgaan en wanneer u een actie uitvoert (zoals op een verzendknop drukken), wordt een verzendverzoek verzonden samen met alle contextuele informatie die de webserver nodig heeft om dat verzoek te verwerken ( zoals gebruikersnaam, tokens, enz.). De applicatie gaat van de ene toestand naar de andere, maar zonder een constante behoefte aan verbinding tussen de client en de server.
REST definieert een reeks beperkingen tussen de client en de server, en de communicatie kan alleen plaatsvinden onder die beperkingen. REST over HTTP gebruikt bijvoorbeeld meestal het CRUD-model, dat staat voor Create, Read, Update en Delete en HTTP-methoden zoals POST, GET, PUT en DELETE helpen u bij het uitvoeren van die bewerkingen en die bewerkingen alleen. Oude inbraaktechnieken zoals SQL-injecties zijn niet mogelijk met zoiets als een strak geschreven REST API (hoewel het REST is, is het geen beveiligingswonder).
Het helpt ook veel UI-ontwikkelaars! Aangezien alles wat u van een HTTP-verzoek ontvangt typisch een stroom tekst is (soms geformatteerd als JSON), kunt u eenvoudig een webpagina voor browsers of een app (in uw voorkeurstaal) implementeren zonder u zorgen te maken over de server-side architectuur. U leest de API-documentatie voor services zoals Reddit, Twitter of Facebook en u kunt extensies voor hen of externe clients schrijven in de taal van uw keuze, aangezien u er zeker van bent dat het gedrag van de API nog steeds hetzelfde zal zijn.
Omgekeerd maakt het de server niet uit of de front-end is geschreven in Go, Ruby of Python. Of het nu een browser, app of een CLI . is. Het 'ziet' het verzoek gewoon en reageert adequaat.
Wat is GraphQL?
Zoals met alles in de wereld van computers, werden REST API's groter en complexer en tegelijkertijd wilden mensen ze op een snellere en eenvoudigere manier implementeren en consumeren. Dit is de reden waarom Facebook op het idee kwam van GraphQL, en het later open source maakte. De QL in GraphQL staat voor Query Language.
Met GraphQL kunnen klanten zeer specifieke API-verzoeken doen, in plaats van starre API-aanroepen te doen met vooraf gedefinieerde parameters en antwoorden. Het is veel eenvoudiger omdat de server dan reageert met precies de gegevens waar je om hebt gevraagd, zonder overdaad.
Bekijk dit REST-verzoek en het bijbehorende antwoord. Dit verzoek is bedoeld om alleen de openbare bio van een gebruiker te bekijken.
Verzoek: KRIJG https://api.github.com/gebruikers/Reactie:
"login": "octocat",
"id": 583231,
"node_id": "MDQ6VXNlcjU4MzIzMQ==",
"avatar_url": "https://avatars3.githubusercontent.com/u/583231?v=4",
"gravatar_id": "",
"url": "https://api.github.com/users/octocat",
"html_url": "https://github.com/octocat",
"followers_url": "https://api.github.com/users/octocat/volgers",
"following_url": "https://api.github.com/users/octocat/following/other_user",
"gists_url": "https://api.github.com/users/octocat/gists/gist_id",
"starred_url": "https://api.github.com/users/octocat/starred/owner/repo",
"subscriptions_url": "https://api.github.com/users/octocat/abonnementen",
"organizations_url": "https://api.github.com/users/octocat/orgs",
"repos_url": "https://api.github.com/users/octocat/repos",
"events_url": "https://api.github.com/users/octocat/events/privacy",
"received_events_url": "https://api.github.com/users/octocat/received_events",
"type": "Gebruiker",
"site_admin": false,
"naam": "De Octocat",
"bedrijf": "GitHub",
"blog": "http://www.github.com/blog",
"locatie": "San Francisco",
"e-mail": null,
"in te huren": null,
"bio": null,
"public_repos": 8,
"public_gists": 8,
"volgers": 2455,
"volgend": 9,
"created_at": "2011-01-25T18:44:36Z",
"updated_at": "2018-11-22T16:00:23Z"
Ik heb de gebruikersnaam octocat gebruikt, maar je kunt deze vervangen door de gebruikersnaam van je keuze en cURL gebruiken om dit verzoek in de opdrachtregel of Postman te doen als je een GUI nodig hebt. Hoewel het verzoek eenvoudig was, denk eens na over alle extra informatie die u uit dit antwoord krijgt. Als u gegevens van een miljoen van dergelijke gebruikers zou verwerken en alle onnodige gegevens eruit zou filteren, dan is dat niet efficiënt. U verspilt bandbreedte, geheugen en rekenkracht bij het verkrijgen, opslaan en wegfilteren van alle miljoenen extra sleutel-waardeparen die u nooit zult gebruiken
Ook de structuur van de respons weet je niet van tevoren. Dit JSON-antwoord is gelijk aan een woordenboekobject in Python of een object in JavaScript. Andere eindpunten zullen reageren met JSON-objecten die kunnen zijn samengesteld uit geneste objecten, een geneste lijst binnen het object of een willekeurige combinatie van JSON-gegevenstypen, en u moet de documentatie raadplegen om de details te krijgen. Wanneer u het verzoek verwerkt, moet u op de hoogte zijn van dit formaat dat van eindpunt naar eindpunt verandert.
GraphQL vertrouwt niet op HTTP-werkwoorden zoals POST, GET, PUT en DELETE om CRUD-bewerkingen op de server uit te voeren. In plaats daarvan is er slechts één type HTTP-verzoektype en endopint voor alle CRUD-gerelateerde bewerkingen. In het geval van GitHub gaat het om verzoeken van het type POST met slechts één eindpunt https://api.github.com/graphql
Omdat het een POST-verzoek is, kan het een JSON-achtige tekst bevatten waarmee onze GraphQL-bewerkingen kunnen worden uitgevoerd. Deze bewerkingen kunnen van het type zijn vraag als het alleen wat informatie wil lezen, of het kan een mutatie voor het geval gegevens moeten worden gewijzigd.
Om GraphQL API-aanroepen te doen, kunt u de GraphQL-verkenner van GitHub gebruiken. Bekijk deze GraphQL vraag om dezelfde soort gegevens (de openbare bio van een gebruiker) op te halen als hierboven met REST.
Verzoek: POST https://api.github.com/graphqlvraag
gebruiker (login: "ranvo")
bio
Reactie:
"gegevens":
"gebruiker":
"bio": "Tech- en wetenschapsenthousiastelingen. Ik hou van allerlei niet-gerelateerde dingen van
servers naar kwantumfysica.\r\nAf en toe schrijf ik blogberichten over bovenstaande interesses."
Zoals je kunt zien, bestaat het antwoord alleen uit waar je om hebt gevraagd, dat is de bio van de gebruiker. U selecteert een specifieke gebruiker door de gebruikersnaam door te geven (in mijn geval is het ranvo) en dan vraag je naar de waarde van een attribuut van die gebruiker, in dit geval is dat attribuut bio. De API-server zoekt de exacte specifieke informatie op en reageert daarmee en niets anders.
Aan de andere kant laat GraphQL u ook een enkel verzoek doen en informatie extraheren waarvoor u meerdere verzoeken zou hebben gekregen in de traditionele REST API. Bedenk dat alle GraphQL-verzoeken aan slechts één API-eindpunt worden gedaan. Neem bijvoorbeeld de use case waarbij u de GitHub API-server moet vragen om de bio van de gebruiker en een van zijn SSH-sleutels. Er zijn twee GET-verzoeken nodig.
REST-verzoeken: KRIJG https://api.github.com/KRIJG https://api.github.com/
GraphQL-verzoek: POST https://api.github.com/graphql/
vraag
gebruiker (login: "ranvo")
bio
publicKeys (laatste:1)
randen
knoop
sleutel
GraphQL-reactie:
"gegevens":
"gebruiker":
"bio": "Tech- en wetenschapsenthousiastelingen. Ik hou van allerlei niet-gerelateerde dingen van
servers naar kwantumfysica physi.\r\nAf en toe schrijf ik blogberichten over bovenstaande interesses.",
"publicKeys":
"randen": [
"knooppunt":
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Er zijn geneste objecten, maar als je naar je verzoek kijkt, komen ze vrijwel overeen met je verzoek, zodat je de structuur van het antwoord dat je krijgt, kunt kennen en in zekere zin vorm kunt geven .
Conclusie
GraphQL heeft zijn eigen leercurve, die erg steil of helemaal niet steil is, afhankelijk van wie je het vraagt. Objectief gezien kan ik de volgende feiten voor je opsommen:. Het is flexibel zoals je hierboven hebt gezien, het is introspectief - dat wil zeggen, je kunt de GraphQL API opvragen over de API zelf. Zelfs als u uw API-server er niet mee gaat bouwen, is de kans groot dat u moet communiceren met een API die alleen GraphQL toestaat.
U kunt hier wat meer te weten komen over de technische aspecten ervan en als u GraphQL API-aanroepen wilt doen vanaf uw lokale werkstation, gebruik dan Graphiql.
