Connecting to GraphQL
DreamFactory can connect to GraphQL, using Graphiql as its IDE. This tutorial explains how to configure DreamFactory to make connections to a GraphQL instance, enabling the use of queries and mutations to view and modify data you are pushing to various data systems.
Contents
What is GraphQL
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.
Create a new app
- Start by creating a new app in the Admin Dashboard named whatever you like. For ease of use, I recommending something very creative, such as GraphQL, or GraphiQL as we forked this 3rd party, in-browser IDE to perform the query and mutation events.
- Make sure to mark the app active and assign a default role to it. Make sure the role has the correct privileges in order to interact with the service.
- There are other ways to do this, but by creating an app you have an easy way to acquire the API key you will need later.
Install the software
- Once you get the app created it is time to start the install. You will need to edit your composer.json file. You need to edit the file in two places: The first is under the repositories statement and the second is under the require statement.
- Under the repositories statement, you need to add the type and URL for the code. It will be an object inside of the repositories array.
{
“Type”: “vcs”,
“url”: “https://github.com/dreamfactorysoftware/df-graphiql”
}- Under the require statement add in the dependency for df-graphiql
{
“dreamfactory/df-graphiql”: “dev-develop as dev-master”,
}- Update the composer.json file to install the dependencies:
composer update dreamfactory/df-graphiql --no-dev
- Clear the cache:
php artisan cache:clear- Next, edit the graphiql package to add the Dreamfactory API key
vim vendor/dreamfactory/df-graphiql/resources/views/graphiql.php
- Locate the API key section under the following note:
//Defines a GraphQL fetcher using the fetch API- You will see the headers object. This is where you need to put your key:
‘X-DreamFactory-API-key’: ‘YOUR_API_KEY’
Head back to the Launchpad section of your DreamFactory instance and you can run the Graphiql app. This gives you a basic idea of some of the commands for GraphQL If you click on the Docs tab it will give you access to the query and mutation root types. This documentation is all auto-generated from your database connections in DreamFactory. As you click through you can see the type it returns, the arguments, etc.
Examples
- Query:
In this example, we are going to just use a basic query to return the name of a table in our SQL Server database. We are also going to use a query variable so that we have some flexibility in how we pass data into the query for future uses.
We are passing in the name object as a variable in this case. This returns the table information you would see if you hit the table schema endpoint:
