mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-17 04:24:35 +03:00
866476ab36
GITHUB_PR_NUMBER: 8011 GITHUB_PR_URL: https://github.com/hasura/graphql-engine/pull/8011 PR-URL: https://github.com/hasura/graphql-engine-mono/pull/3317 Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: 90c8f75003a07c5153c9e478efa599ab0bfb85d9
159 lines
4.9 KiB
ReStructuredText
159 lines
4.9 KiB
ReStructuredText
.. meta::
|
|
:description: Hasura RESTified GraphQL API reference
|
|
:keywords: hasura, docs, REST API, API reference
|
|
|
|
.. _restified_api_reference:
|
|
|
|
RESTified GraphQL Endpoints API Reference
|
|
=========================================
|
|
|
|
.. contents:: Table of contents
|
|
:backlinks: none
|
|
:depth: 1
|
|
:local:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
The RESTified GraphQL API allows for the use of a REST interface to saved GraphQL queries and mutations.
|
|
|
|
Users specify the query or mutation they wish to make available, as well a URL template.
|
|
Segments of the URL template can potentially capture data to be used as GraphQL variables.
|
|
|
|
See :ref:`metadata_api_restified_endpoints` for information on how to work with endpoints through the metadata apis.
|
|
|
|
.. admonition:: Supported from
|
|
|
|
RESTified endpoints are supported from versions ``v2.0.0-alpha.1`` and above.
|
|
|
|
Endpoint
|
|
--------
|
|
|
|
Requests are made to ``/api/rest/**`` endpoints.
|
|
|
|
By default these are:
|
|
|
|
* ``GET``, ``POST`` requests for queries, and
|
|
* ``POST`` requests for mutations
|
|
|
|
Although not in the REST spirit, ``POST`` requests are allowed by default for
|
|
non-mutation queries since some HTTP clients may not be able to supply a JSON
|
|
body for GET requests.
|
|
|
|
If required, users may explicitly configure the HTTP methods allowed per endpoint.
|
|
|
|
|
|
API Spec
|
|
--------
|
|
|
|
Request
|
|
^^^^^^^
|
|
|
|
Endpoints are determined by the URL templates:
|
|
|
|
* Simple URLs such as ``/s1/s2/s3`` match literally.
|
|
* Segments starting with a ``:`` treat these parts of the path like wildcards and use the name to assign a variable. For example: ``/s1/:id/s3``.
|
|
|
|
|
|
The request expects a normal REST style request to the endpoint.
|
|
|
|
Variables can be supplied via route patterns, url query variables, and request body JSON object keys.
|
|
|
|
* JSON Body Object values are passed directly to the associated query with no additional validation or type-coersion.
|
|
* Route variables and Query parameters are interpreted as scalars according to the variables types in the associated query and passed as JSON data through the query variables:
|
|
|
|
* Missing nullable variables are interpreted as ``NULL``
|
|
* Boolean variables are interpreted as ``Boolean``
|
|
* Boolean flags without values e.g. ``/api/rest/myquery?mybool`` are interpreted as ``true``
|
|
* String variables are interpreted as ``String``
|
|
* UUID variables are interpreted as ``String``
|
|
* ID variables are interpreted as ``String``
|
|
* Number, Int, Float, and Double variables are interpreted as ``Number``
|
|
* **All other types or mismatches currently report variable type errors**
|
|
|
|
|
|
When making a request to this API only one endpoint should match. If multiple endpoints match your request this is considered an error and will report so via a 500 status code. If endpoints exist with your path, but none matching your HTTP method then a 405 error will be returned
|
|
listing the methods that you can use.
|
|
|
|
Sample requests
|
|
***************
|
|
|
|
|
|
.. code-block:: http
|
|
|
|
GET /api/rest/simple_query/1 HTTP/1.1
|
|
|
|
.. code-block:: http
|
|
|
|
POST /api/rest/complicated_mutation/2?time=now HTTP/1.1
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"user": {"name": "Simon"}
|
|
}
|
|
|
|
|
|
Response
|
|
^^^^^^^^
|
|
|
|
The response is determined by the saved query. The response will be the same as if you had made the query directly in the GraphQL console.
|
|
|
|
See the :ref:`api_reference_graphql` for more details.
|
|
|
|
|
|
OpenAPI 3 Specification
|
|
---------------------------
|
|
|
|
The OpenAPI 3 specification of the REST endpoints are exposed at ``/api/swagger/json`` for admin role only:
|
|
|
|
.. code-block:: http
|
|
|
|
GET /api/swagger/json HTTP/1.1
|
|
X-Hasura-Role: admin
|
|
|
|
The response JSON will be a OpenAPI 3 specification (OAS 3.0) for all the
|
|
RESTified GraphQL Endpoints for admin roles. For more details about OAS 3.0,
|
|
`click here <https://swagger.io/specification/>`__.
|
|
|
|
Sample request
|
|
^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: http
|
|
|
|
GET /api/swagger/json HTTP/1.1
|
|
X-Hasura-Role: admin
|
|
|
|
Response
|
|
^^^^^^^^
|
|
|
|
.. code-block:: JSON
|
|
|
|
{
|
|
"openapi": "3.0.0",
|
|
"info": {
|
|
"version": "",
|
|
"title": "Rest Endpoints",
|
|
"description": "These OpenAPI specifications are automatically generated by Hasura."
|
|
},
|
|
"paths": {
|
|
"/api/rest/users": {
|
|
"get": {
|
|
"summary": "Fetch user data",
|
|
"description": "This API fetches user data (first name and last name) from the users table.\n***\nThe GraphQl query for this endpoint is:\n``` graphql\nquery MyQuery{\n users {\n first_name\n last_name\n }\n}\n```",
|
|
"responses": {}
|
|
},
|
|
"parameters": [
|
|
{
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"in": "header",
|
|
"name": "x-hasura-admin-secret",
|
|
"description": "Your x-hasura-admin-secret will be used for authentication of the API request."
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"components": {}
|
|
}
|