Module graphqlapi.lua
is a main module which provides general functions to init/stop/reload module and also for setting/getting http-endpoint, setting/getting middleware and setting/getting GraphQLAPI fragments dir path.
It can be loaded by the following code:
local graphqlapi = require('graphqlapi')
If module runs in Tarantool Cartridge Application Role you can also use the following syntax:
local cartridge = require('cartridge')
local graphqlapi = cartridge.service_get('graphqlapi')
graphqlapi.init(httpd, middleware, endpoint, fragments_dir, opts)
- method is used to initialize GraphQLAPI module,
where:
httpd
(table
) - optional (may be absent only ifopts.enable_iproto
istrue
), instance of a Tarantool HTTP server;middleware
(table
) - optional (must not be provided ifhttpd
is not provided), instance of set of middleware callbacks;endpoint
(string
) - optional (must not be provided ifhttpd
is not provided), URI of http endpoint to be used for interacting with GraphQLAPI module, default value:http(s)://<server:port>/admin/graphql
;fragments_dir
(string
) - optional, path to dir with customer GraphQL fragments, default value:<app_root>/fragments
;opts
(table
) - optional, options of http-route and GraphQL API specific options:- options are the same as http:route HTTP routes
enable_iproto
(boolean
) - optional, if trueexecute_graphql
function will be set as global to make possible to make GraphQL requests over IPROTO.
execute_graphql(request)
- is a special function may be set as global by enable_iproto
option on init()
or by calling a special method graphqlapi.init_graphql_iproto()
,
where:
request
(table
) - mandatory, GraphQL request with the following map:query
(string
) - mandatory, GraphQL query;operationName
(string
) - optional, the name of GraphQL operation to be executed;variables
(table
) - optional, a dictionary with operation variables values;schema
(string
) - optional, the name of schema query belongs to, if not provideddefaults.DEFAULT_SCHEMA_NAME
is used,
returns:
[1]
(table
) - result of GraphQL query or nil if error;
[2]
(table
) - array of error objects if any.
Note: According to GraphQL specification GraphQL may return: result
, result == nil and error(s)
and also result and error(s)
. This fact must be taken into account when handling errors.
Examples:
GraphQL over HTTP:
local http = require('http.server')
local graphqlapi = require('graphqlapi')
local HOST = '0.0.0.0'
local PORT = 8081
local ENDPOINT = '/graphql'
box.cfg({work_dir = './tmp'})
local httpd = http.new(HOST, PORT,{ log_requests = false })
httpd:start()
graphqlapi.init(httpd, nil, ENDPOINT, '../example/fragments')
GraphQL over IPROTO:
local graphqlapi = require('graphqlapi')
graphqlapi.init(nil, nil, nil, '../example/fragments', { enable_iproto = true })
graphqlapi.execute_graphql({query = 'query MyQuery { }', operationName = 'MyQuery', variables = {}, schema = 'Default'})
graphqlapi.stop()
- method is used to deinit GraphQL API module, remove all used variables, cleanup cache and destroy http-endpoint.
graphqlapi.reload()
- method is used to reload all fragments from disk. Usually used to load new fragments, that may be placed to the same fragments_dir.
graphqlapi.set_fragments_dir(fragments_dir)
- method is used to get GraphQL API fragments dir path,
where:
fragments_dir
(string
) - mandatory, path to GraphQL API fragments. Base path - is the path to root dir of the application, but absolute path is also possible.
Example:
local graphqlapi = require('graphqlapi')
graphqlapi.set_fragments_dir('fragments')
graphqlapi.get_fragments_dir()
- method is used to get GraphQL API fragments dir path,
Returns fragments_dir
(string
) - path to GraphQL API fragments.
Example:
local graphqlapi = require('graphqlapi')
local log = require('log')
local fragments_dir = graphqlapi.get_fragments_dir()
log.info('GraphQL API fragments dir path: %s', fragments_dir)
graphqlapi.set_endpoint(endpoint)
- method is used to set endpoint in runtime.
where:
endpoint
(string
) - mandatory, URI-endpoint of GraphQL API.
Example:
local graphqlapi = require('graphqlapi')
local endpoint = '/admin/graphql'
graphqlapi.set_endpoint(endpoint)
graphqlapi.get_endpoint()
- method is used to get endpoint.
Returns:
endpoint
(string
).
Example:
local graphqlapi = require('graphqlapi')
local log = require('log')
local graphqlapi_endpoint = graphqlapi.get_endpoint()
log.info('GraphQL API endpoint: %s', graphqlapi_endpoint)
graphqlapi.set_middleware(http_middleware)
- method is used to set custom middleware triggers,
where:
http_middleware
(table
) - mandatory, table with one or more provided middleware functions:
http_middleware = {
render_response = function(resp) return resp end,
request_wrapper = function(handler) return handler end,
authorize_request = function(req) return true end,
}
For more detailed info about this triggers refer to middleware submodule.
Example:
local graphqlapi = require('graphqlapi')
local http_middleware = require('middleware')
graphqlapi.set_endpoint(http_middleware)
graphqlapi.get_middleware()
- method is used to set custom middleware triggers,
returns:
[1]
(table
) - current http-middleware triggers. For more info refer to middleware submodule.
init_graphql_iproto()
- method is used to set execute_graphql
as a global function to make possible to make GraphQL requests over IPROTO.
stop_graphql_iproto()
- method is used to remove execute_graphql
from global functions to make impossible to make GraphQL requests over IPROTO if execute_graphql
was previously set as a global function.
GraphQLAPI module and Tarantool Cartridge role has VERSION
constant to determine which version is installed.
Example:
local graphqlapi = require('graphqlapi')
local log = require('log')
log.info('GraphQL API version: %s', graphqlapi.VERSION)