Phenquestions
TL; DR версия
В една от предишните публикации обсъдихме накратко какво е да използвате GitHub API v3. Тази версия е проектирана да бъде свързана като всеки друг REST API. Има крайни точки за всеки ресурс, до който се нуждаете за достъп и / или промяна. Има крайни точки за всеки потребител, всяка организация, всяко хранилище и така нататък. Например, всеки потребител има своя крайна точка на API на https: // api.github.com / потребители /
GitHub API v4, от друга страна, използва GraphQL, където QL означава Query Language. GraphQL е нов начин за проектиране на вашите API. Точно както има много уеб услуги, предлагани като REST API, не само тези, предлагани от GitHub, има много уеб услуги, които ви позволяват да взаимодействате с тях чрез GraphQL.
Най-ярка разлика, която ще забележите между GraphQL и REST API е, че GraphQL може да работи с една крайна точка на API. В случай на GitHub API v4, тази крайна точка е https: // api.github.com / graphql и това е всичко. Не е нужно да се притеснявате за добавяне на дълги низове в края на корен URI или да предоставите параметър на низ за заявка за допълнителна информация. Просто изпращате аргумент като JSON като този API, като искате само нещата, от които се нуждаете, и ще получите обратно полезен товар JSON с точно същата информация, която сте поискали. Не е нужно да се занимавате с филтриране на нежелана информация или да страдате от натоварване на производителността поради големи отговори.
Какво е REST API?
Е, REST означава представител на държавен трансфер, а API означава интерфейс за програмиране на приложения. REST API или „RESTful“ API се превърна в основната философия на дизайна зад повечето съвременни клиент-сървърни приложения. Идеята възниква от необходимостта да се разделят различни компоненти на приложение като потребителски интерфейс от страна на клиента и логика от страна на сървъра.
Така че сесията между клиент и сървър обикновено е без гражданство. След като уеб страницата и свързаните скриптове се заредят, можете да продължите да взаимодействате с тях и когато извършите действие (като натиснете бутона за изпращане), тогава се изпраща заявка за изпращане заедно с цялата контекстуална информация, необходима на уеб сървъра, за да обработи тази заявка ( като потребителско име, токени и т.н.). Приложението преминава от едно състояние в друго, но без постоянна нужда от връзка между клиента и сървъра.
REST определя набор от ограничения между клиента и сървъра и комуникацията може да се осъществи само при тези ограничения. Например REST през HTTP обикновено използва модела CRUD, който означава Създаване, четене, актуализиране и изтриване, а HTTP методите като POST, GET, PUT и DELETE ви помагат да извършвате тези операции и тези операции сами. Старите техники за проникване като SQL инжекции не са възможни с нещо като строго написан REST API (въпреки че REST не е панацея за сигурност).
Също така помага много на разработчиците на потребителски интерфейс! Тъй като всичко, което получавате от HTTP заявка, е типичен поток от текст (форматиран като JSON, понякога), можете лесно да внедрите уеб страница за браузъри или приложение (на предпочитания от вас език), без да се притеснявате за архитектурата от страна на сървъра. Четете документацията на API за услуги като Reddit, Twitter или Facebook и можете да напишете разширения за тях или клиенти на трети страни на избрания от вас език, тъй като сте сигурни, че поведението на API ще остане същото.
И обратно, сървъра не се интересува дали интерфейсът е написан в Go, Ruby или Python. Независимо дали става дума за браузър, приложение или CLI. Той просто „вижда“ заявката и реагира адекватно.
Какво е GraphQL?
Както при всичко в света на компютрите, REST API стават по-големи и по-сложни и в същото време хората искат да ги внедрят и консумират по-бързо и по-просто. Ето защо Facebook излезе с идеята за GraphQL и по-късно я отвори. QL в GraphQL означава Query Language.
GraphQL позволява на клиентите да правят много специфични заявки за API, вместо да правят твърди API извиквания с предварително зададени параметри и отговори. Това е много по-просто, защото след това сървърът отговаря с точно данните, за които сте го поискали, без нищо излишно.
Разгледайте тази REST заявка и съответния й отговор. Тази заявка е предназначена да види само публичната биография на потребителя.
Заявка: ВЗЕМЕТЕ https: // api.github.com / потребители /Отговор:
"login": "octocat",
"id": 583231,
"node_id": "MDQ6VXNlcjU4MzIzMQ ==",
"avatar_url": "https: // avatars3.githubuserсъдържание.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 / followers ",
"following_url": "https: // api.github.com / users / octocat / follow / other_user ",
"gists_url": "https: // api.github.com / users / octocat / gists / gist_id ",
"starred_url": "https: // api.github.com / users / octocat / със звезда / owner / repo ",
"subscription_url": "https: // api.github.com / users / octocat / абонаменти ",
"organization_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": "Потребител",
"site_admin": невярно,
"name": "Октокотът",
"company": "GitHub",
"блог": "http: // www.github.com / blog ",
"location": "Сан Франциско",
"имейл": нула,
"hireable": null,
"био": нула,
"public_repos": 8,
"public_gists": 8,
„последователи“: 2455,
"след": 9,
"created_at": "2011-01-25T18: 44: 36Z",
"updated_at": "2018-11-22T16: 00: 23Z"
Използвах потребителското име octocat, но можете да го замените с избраното от вас потребителско име и да използвате cURL, за да направите тази заявка в командния ред или Postman, ако имате нужда от GUI. Въпреки че заявката беше проста, помислете за цялата допълнителна информация, която получавате от този отговор. Ако трябва да обработвате данни от милион такива потребители и да филтрирате всички ненужни данни, използвайки това, това не е ефективно. Пропилявате честотна лента, памет и изчисления за получаване, съхраняване и филтриране на всички милиони допълнителни двойки ключ-стойност, които никога няма
Също така структурата на отговора не е нещо, което знаете предварително. Този JSON отговор е еквивалентен на обект в речника в Python или обект в JavaScript. Други крайни точки ще отговорят с JSON обекти, които могат да се състоят от вложени обекти, вложен списък в обекта или произволна комбинация от типове данни JSON и ще трябва да прегледате документацията, за да получите подробностите. Когато обработвате заявката, трябва да сте наясно с този формат, който се променя от крайна точка до крайна точка.
GraphQL не разчита на HTTP глаголи като POST, GET, PUT и DELETE за извършване на CRUD операции на сървъра. Вместо това има само един тип HTTP тип заявка и endopint за всички операции, свързани с CRUD. В случай на GitHub това включва заявки от тип POST само с една крайна точка https: // api.github.com / graphql
Като POST заявка, той може да носи със себе си JSON като текст, чрез който ще бъдат нашите GraphQL операции. Тези операции могат да бъдат от типa заявка ако всичко, което иска да направи, е да прочете някаква информация или може да е a мутация в случай, че данните трябва да бъдат модифицирани.
За да извършвате API на GraphQL, можете да използвате GraphQL Explorer на GitHub. Погледнете този GraphQL заявка за извличане на същия вид данни (публична биография на потребителя), както направихме по-горе, използвайки REST.
Заявка: POST https: // api.github.com / graphqlзаявка
потребител (вход: "ranvo")
био
Отговор:
"данни":
"потребител":
"bio": "Технологични и научни ентусиасти. Аз съм във всякакви несвързани неща от
сървъри за квантова физика.\ r \ n Понякога пиша публикации в блога за горепосочените интереси."
Както можете да видите, отговорът се състои само от това, което сте поискали, това е биографията на потребителя. Можете да изберете конкретен потребител, като предадете потребителското име (в моя случай това е ранво) и след това питате за стойността на атрибут на този потребител, в този случай този атрибут е био. API сървърът търси точно конкретната информация и отговаря с това и с нищо друго.
От друга страна, GraphQL също ви позволява да направите една заявка и да извлечете информация, която би ви отнела множество заявки в традиционния REST API. Спомнете си, че всички заявки на GraphQL се правят само до една крайна точка на API. Вземете например случая на използване, където трябва да попитате GitHub API сървъра за биографията на потребителя и един от неговите SSH ключове. Това ще изисква две GET заявки.
ОТСТАНОВИ Искания: ВЗЕМЕТЕ https: // api.github.com /ВЗЕМЕТЕ https: // api.github.com /
Искане на GraphQL: POST https: // api.github.com / graphql /
заявка
потребител (вход: "ranvo")
био
publicKeys (последно: 1)
ръбове
възел
ключ
Отговор на GraphQL:
"данни":
"потребител":
"bio": "Технологични и научни ентусиасти. Аз съм във всякакви несвързани неща от
сървъри за квантова физика.\ r \ n Понякога пиша публикации в блога за горепосочените интереси.",
"publicKeys":
"ръбове": [
"възел":
"ключ": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIH31mVjRYdzeh8oD8jvaFpRuIgL65SwILyKpeGBUNGOT"
]
Има вложени обекти, но ако погледнете вашата заявка, те почти съвпадат с вашата заявка, за да можете да знаете и в някакъв смисъл да оформите структурата на отговора, който получавате .
Заключение
GraphQL идва със собствена крива на обучение, която е много стръмна или изобщо не е стръмна, в зависимост от това кого питате. От обективна гледна точка мога да ви представя следните факти. Той е гъвкав, както видяхте по-горе, той е интроспективен - тоест, можете да попитате API на GraphQL за самия API. Дори и да нямате намерение да изграждате вашия API сървър, използвайки го, има вероятност ще трябва да взаимодействате с API, който позволява само GraphQL.
Можете да научите малко повече за техническите му характеристики тук и ако искате да осъществите обаждания към API на GraphQL от вашата локална работна станция, използвайте Graphiql.
