GraphQL API Queries

GraphQL is a different type of REST request you can use on FlexDeploy servers. It’s main advantage over traditional REST Endpoints is its ability for a user to define exactly the data they want in a request. The request will only retrieve the data selected in a request. This can lead to better response times and more customizable data retrieval from a server. To get started, a tool is needed in in order to send requests to your FlexDeploy server. Several options exist like curl or other REST clients, but we will be using Postman in order to send out GraphQL requests.

Basics

Basic auth is supported for accessing FlexDeploy’s GraphQL Endpoint. Username and password or API Token are both supported.

FlexDeploy’s GraphQL Endpoint:

http(s)://{{FLEXDEPLOY_SERVER_HOSTNAME}}:{{FLEXDEPLOY_SERVER_PORT}}/flexdeploy/rest/v2/graphql

Example:

https://flexdeployserver.hostingservice.com:8000/flexdeploy/rest/v2/graphql

Making a Request

First, there are some steps in Postman that need to be done before writing a request.

  1. Create an HTTP Request

  2. Make sure the Request is a POST request

  3. Set the URL to the endpoint listed above in Basics, replacing the {{FLEXDEPLOY_SERVER_HOSTNAME}} and {{FLEXDEPLOY_SERVER_PORT}} with your FlexDeploy server’s hostname and port respectively

  4. Set up security information under the “Authorization” tab. Either Basic Auth (username and password) or an API token can be used here

  5. Under the “Body” tab of the request, switch the body format to GraphQL by clicking on the “GraphQL” radio button

Fetching Schema and Introspection

A GraphQL schema is a complete outline of what data is available when sending a query to the server. In order to learn what data is available when making a request, the schema can be fetched from the server. Once the URL and authentication are provided, Postman will automatically fetch the schema from the server and use it in autocomplete to help with writing queries. Otherwise, an Introspection Query can provide a list of queries accessible in our schema if this auto-fetch feature is unavailable .

To have Postman give suggestions for your query, press Ctrl + Space to bring up the autocomplete box.

Writing a Query

After you have created a request and loaded the schema, we can start to write our query. There are a few key parts to a query which we’ll dive into with the example below.

query envState($where: [WhereInput], $sort: [SortInput], $page: PageInput) { reportEnvironmentState(where: $where, sort: $sort, page: $page) { items { endTime environmentName executionStatus externalTicket instanceName objectPath packageName partialDeployments projectName projectVersionName projectWorkflowType relName relSnapshot scmRevision startTime streamName workflowExecutionId workflowRequestId } } }

We can see that we are running the reportEnvironmentState query (Environment State Report). This query has three variables (where, sort, and page) and is selecting quite a few fields in the “items” section to return when it executes.

Selection Set

The biggest difference between GraphQL and other, more traditional, REST requests are the optional selection of elements to be returned in a query. This can make queries return faster if only the information that is needed by the query is returned. This is called a subselection set. In our example we can see we have this block of text:

Here is where we can control what is being returned in the query. GraphQL will only return fields present in the subselection. For example, if I only wanted Package Name, Project Name, and Project Version Name to be returned, I could alter our previous example to something like this:

Variables

There are three main variables that are common across most FlexDeploy GraphQL queries: where, sort, and page.

Variable Name

Description

Object Definition

Variable Name

Description

Object Definition

where: [WhereInput]

This allows you to filter the data like a where clause in an SQL query. Where is an array so multiple individual WhereInput objects can be linked together to filter the query.

field: Name of the GraphQL field being filtered

type: The comparison being performed

  • eq - equal

  • ne - not equal

  • eqi - equal (Ignores Case)

  • gt - greater than

  • lt - less than

  • inc - includes

  • inci - includes (Ignores Case)

  • ninc - does not include

  • empty - empty

  • nempty - not empty

innerWhere: Similar to a subselect in SQL where prefiltering of a query could be done

value: The value you are filtering by

sort: [SortInput]

This allows you to sort the data like a order by clause in an SQL query. Sort is an array so multiple individual SortInput objects can be linked together to sort the query.

field: GraphQL field being sorted

direction: the direction of sort being preformed with asc meaning ascending order and desc meaning descending order.

page: PageInput

Page input contains extra options for the block of data that is returned by the query.

limit: The number of items in the block being returned. By default, a limit of 50 items are returned by the query. This can be overridden by the page limit to return a different amount of items.

offset: Offsets the block of data being returned by the set value. For example, a limit of 20 and an offset of 4 would return items 4 through 23.

 

All of the above variables objects are then bundled together in one variable object. It is not required to always include all three variables in the object. For example, if you wanted to only filter and not sort, you would only need to include the where variable. Below is an example of the combined variable object with all three variables used.

Executing A Query

Combining everything we talked about thus far (creating a HTTP Request, queries, and variables), we are now able to execute a query.

Response

Example Queries

Here are are few more examples of GraphQL queries. See Fetching Schema and Introspection for information on how to get our schema for a full listing of available queries and mutations.

Environment History Report with File Details

This is running the same query used by the Environment History Report with the Show File Details checkbox selected. It is querying the history of all FlexDeploy executions against an environment called “Build” with file-level details being returned. We have a where variable below being used to only filter for the Build environment, as well as a page variable to limit the response to only the first two items.

Variables
Response

Environment History Report without File Details

This is querying the history of our production deployments that failed with file details not being returned. We also want the most recent failed deployment so we will be sorting by date.

Variables
Response
The following macros are not currently supported in the footer:
  • style