{"meta":{"title":"Миграция из REST в GraphQL","intro":"Изучите лучшие практики и рекомендации по миграции с GitHubREST API на GitHubGraphQL от GraphQL.","product":"API GraphQL","breadcrumbs":[{"href":"/ru/enterprise-cloud@latest/graphql","title":"API GraphQL"},{"href":"/ru/enterprise-cloud@latest/graphql/guides","title":"Guides"},{"href":"/ru/enterprise-cloud@latest/graphql/guides/migrating-from-rest-to-graphql","title":"Миграция из REST в GraphQL"}],"documentType":"article"},"body":"# Миграция из REST в GraphQL\n\nИзучите лучшие практики и рекомендации по миграции с GitHubREST API на GitHubGraphQL от GraphQL.\n\n## Отличия в логике API\n\nGitHub предоставляет два API: REST API и GraphQL API. Для получения дополнительной информации об GitHubAPI с (AUTOTITLE) см. [Сравнение REST API GitHub и GraphQL API](/ru/enterprise-cloud@latest/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api).\n\nМиграция из REST в GraphQL сопровождается существенным изменением в логике API. Различия между стилем REST и спецификацией GraphQL затрудняют— и часто делают нежелательной— замену вызовов REST API на запросы API GraphQL один к одному. Ниже приведены примеры миграции.\n\nЧтобы перенести код из [REST API](/ru/enterprise-cloud@latest/rest) в GraphQL API, выполните следующие действия:\n\n* ознакомьтесь со [спецификацией GraphQL](https://spec.graphql.org/June2018/);\n* Пересмотрите схему GitHub [GraphQL](/ru/enterprise-cloud@latest/graphql/reference)\n* Подумайте, как ваш существующий код взаимодействует с API GitHub REST\n* Используйте [Global Node IDs](/ru/enterprise-cloud@latest/graphql/guides/using-global-node-ids) для ссылок на объекты между версиями API\n\nК значительным преимуществам GraphQL относятся:\n\n* [получение только необходимых данных](#example-getting-the-data-you-need-and-nothing-more);\n* [вложенные поля](#example-nesting);\n* [Строгая типизация](#example-strong-typing)\n\nНиже приведены примеры каждого из них.\n\n## Пример: получение только необходимых данных\n\nОдин вызов REST API получает список участников вашей организации:\n\n```shell\ncurl -v https://api.github.com/orgs/:org/members\n```\n\nПолезные данные REST содержат избыточную информацию, и какая-то ее часть окажется ненужной, если вам нужно получить только имена членов и ссылки на аватары. Запрос GraphQL, напротив, возвращает только то, что вы указываете:\n\n```graphql\nquery {\n    organization(login:\"github\") {\n    membersWithRole(first: 100) {\n      edges {\n        node {\n          name\n          avatarUrl\n        }\n      }\n    }\n  }\n}\n```\n\nРассмотрим другой пример: получение списка запросов на включение внесенных изменений и проверка возможности слияния для каждого из них. Вызов REST API получает список запросов на включение внесенных изменений и их [сводные представления](/ru/enterprise-cloud@latest/rest#summary-representations):\n\n```shell\ncurl -v https://api.github.com/repos/:owner/:repo/pulls\n```\n\nЧтобы определить, можно ли выполнить слияние для запроса на включение внесенных изменений, требуется получить каждый запрос на включение внесенных изменений по отдельности ради его [подробного представления](/ru/enterprise-cloud@latest/rest#detailed-representations) (большой объем полезных данных) и проверить, имеет ли его атрибут `mergeable` значение true или false:\n\n```shell\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number\n```\n\nПри использовании GraphQL для каждого запроса на включение внесенных изменений можно получить только необходимые атрибуты `number` и `mergeable`:\n\n```graphql\nquery {\n    repository(owner:\"octocat\", name:\"Hello-World\") {\n    pullRequests(last: 10) {\n      edges {\n        node {\n          number\n          mergeable\n        }\n      }\n    }\n  }\n}\n```\n\n## Пример: вложенные поля\n\nБлагодаря поддержке запросов с вложенными полями можно заменить несколько вызовов REST на меньшее количество запросов GraphQL. Например, получение запроса на включение внесенных изменений вместе с его фиксациями, комментариев без проверки и проверок с помощью **REST API** требует четырех отдельных вызовов:\n\n```shell\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number/commits\ncurl -v https://api.github.com/repos/:owner/:repo/issues/:number/comments\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number/reviews\n```\n\nС помощью **API GraphQL** эти данные можно получить с помощью одного запроса с вложенными полями:\n\n```graphql\n{\n  repository(owner: \"octocat\", name: \"Hello-World\") {\n    pullRequest(number: 1) {\n      commits(first: 10) {\n        edges {\n          node {\n            commit {\n              oid\n              message\n            }\n          }\n        }\n      }\n      comments(first: 10) {\n        edges {\n          node {\n            body\n            author {\n              login\n            }\n          }\n        }\n      }\n      reviews(first: 10) {\n        edges {\n          node {\n            state\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nВы также можете расширить мощность этого запроса, подставив [подставив переменную](/ru/enterprise-cloud@latest/graphql/guides/forming-calls-with-graphql#working-with-variables) номер pull request.\n\n## Пример: строгая типизация\n\nСхемы GraphQL строго типизированы, что делает обработку данных безопаснее.\n\nРассмотрим добавление комментария к проблеме или запросу на включение внесенных изменений с помощью [изменения](/ru/enterprise-cloud@latest/graphql/reference) GraphQL, когда для значения [`clientMutationId`](/ru/enterprise-cloud@latest/graphql/reference/issues#mutation-addcomment) по ошибке было указано целое число вместо строки:\n\n```graphql\nmutation {\n  addComment(input:{clientMutationId: 1234, subjectId: \"MDA6SXNzdWUyMjcyMDA2MTT=\", body: \"Looks good to me!\"}) {\n    clientMutationId\n    commentEdge {\n      node {\n        body\n        repository {\n          id\n          name\n          nameWithOwner\n        }\n        issue {\n          number\n        }\n      }\n    }\n  }\n}\n```\n\nПри выполнении этого запроса возвращаются ошибки с указанием ожидаемых типов для операции:\n\n```json\n{\n  \"data\": null,\n  \"errors\": [\n    {\n      \"message\": \"Argument 'input' on Field 'addComment' has an invalid value. Expected type 'AddCommentInput!'.\",\n      \"locations\": [\n        {\n          \"line\": 3,\n          \"column\": 3\n        }\n      ]\n    },\n    {\n      \"message\": \"Argument 'clientMutationId' on InputObject 'AddCommentInput' has an invalid value. Expected type 'String'.\",\n      \"locations\": [\n        {\n          \"line\": 3,\n          \"column\": 20\n        }\n      ]\n    }\n  ]\n}\n```\n\nЕсли заключить `1234` в кавычки, значение будет преобразовано из целого числа в строку ожидаемого типа:\n\n```graphql\nmutation {\n  addComment(input:{clientMutationId: \"1234\", subjectId: \"MDA6SXNzdWUyMjcyMDA2MTT=\", body: \"Looks good to me!\"}) {\n    clientMutationId\n    commentEdge {\n      node {\n        body\n        repository {\n          id\n          name\n          nameWithOwner\n        }\n        issue {\n          number\n        }\n      }\n    }\n  }\n}\n```"}