Serving over HTTP¶

HTTP - самый распространенный выбор клиент-серверного протокола, когда используется GraphQL, из-за его распространенности. Вот несколько рекомендаций для настройки сервера GraphQL при работе через HTTP.

Web Request Pipeline¶

Большинство современных фреймворков использует модель Pipeline (туннель), в которой запросы проходят через стек промежуточного ПО (известные как фильтры, плагины). Т. к. запрос проходит через туннель, он может быть проверен, преобразован, изменен или прерван с ответом. GraphQL должен быть расположен после всего аутентификационного ПО, чтобы у вас был доступ к той же сессии и информации о пользователе, которую вы получаете в конечных HTTP обработчиках.

URIs, Routes¶

HTTP часто ассоциируется с REST, который использует "ресурсы" как основную концепцию. С другой стороны, концептуальная модель GraphQL - граф сущностей. В результате, сущности в GraphQL не идентифицируются с URL. Вместо этого, сервер GraphQL работает с одним URL (конечной точкой), обычно /graphql, а все запросы GraphQL для данного сервиса должны быть направлены в эту точку.

HTTP Methods, Headers, and Body¶

Ваш GraphQL HTTP сервер должен обрабатывать методы GET и POST.

GET request¶

При получении запроса GET HTTP, запрос GraphQL должен быть указан в query строки запроса. Например, если мы хотим выполнить следующий запрос GraphQL:

1
2
3
4
5

{
  me {
    name
  }
}

Этот запрос может быть отправлен через HTTP GET следующим образом:

1

http://myapi/graphql?query={me{name}}

Переменные запроса могут быть отправленны как JSON строка в дополнительной переменной запроса variables. Если запрос содержит несколько именованных операций, может быть использован параметр запроса operationName для определения, какая именно операция должна быть выполнена.

POST request¶

Стандартный GraphQL POST запрос должен использовать Content-Type header application/json, и включать тело в виде JSON следующего вида:

1
2
3
4
5

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

operationName и variables являются необязательными полями. operationName требуется, только если в запросе присутствует несколько операций.

В дополнение к сказанному выше, мы рекомендуем поддерживать два дополнительных случая:

• Если параметр query в строке запроса присутствует (как в примере выше), он должен быть разобран и обрабатывается таким же образом, как и в случае HTTP GET.
• Если есть Content-Type header application/graphql, необходимо рассматривать содержимое тела HTTP POST так же, как строку query запроса GraphQL.

Если вы используете express-graphql, то это уже включено.

Response¶

Вне зависимости от метода, которым отправляются запрос и переменные, отклик должен быть возвращен в теле запроса в формате JSON. Как отмечено в спецификации, запрос может завершиться возватом данных и каких-то ошибок. Все это должно быть возвращено в JSON объекте в форме:

1
2
3
4

{
  "data": { ... },
  "errors": [ ... ]
}

Если в ответе нет ошибок, поле errors не должно присутствовать в ответе. Если запрос не вернул никакой информации в ответе, в соответствии со спецификацией GraphQL, поле data должно быть включено в запрос только в случае, если во время выполнения запроса возникла ошибка.

GraphiQL¶

GraphiQL полезна во время тестирования и разработки, но должна быть отключена в производстве по умолчанию. Если вы используете express-graphql, вы можете переключить его c помощью переменной окружения NODE_ENV:

1
2
3
4
5
6
7

app.use(
  '/ graphql',
  graphqlHTTP({
    schema: MySessionAwareGraphQLSchema,
    graphiql: process.env.NODE_ENV === 'development',
  })
)

Если вы используете NodeJS, мы рекомендуем использовать express-graphql или graphql-server.

Комментарии