GQL Documentation Page Structure

Summary

Each GraphQL API query and mutation documentation page contains a significant amount of text, and links to related pages with more details — and perhaps some redundancy. To make it easier visually to scan these pages, to find what you need quickly, a certain page structure is used.

Page Structure

Each documentation page for each query and mutation has a basic structure, although it's not used for all pages. There are typically six sections. You can scroll through a documentation page to see them, or you can click on the links to them in the right margin of a page — which are collapsed by default in the GQL documentation.

  • Summary: This describes briefly the function, what information a query will retrieve, and what data it can change for mutations. It's a starting point to understanding the function.

  • Related: Any related functions are listed here, with links to the documentation pages for them.

  • Syntax: This is the syntax for using the function, which includes the fields and their datatypes. It's very clinical and only useful as a as a reference. You'll need to read the subsequent sections to understand how to use a particular function.

  • Example: For almost all functions, a minimal, usually generic example is given of how it may be used. The parameters given are often the required ones only, and the results contain one to three returned values so as not to clutter the page. It's just to enough to provide some clarity since the syntax can be less than obvious.

  • Input Parameters: This is the same as what's contained in the syntax. There usually will be a table listing the parameters that use standard datatypes, with explanations of each. For many of functions, besides standaard datatypes, special datatypes are used. A table for each special datatype will be shown with its parameters and explanations. For each parameter, whether using standard or special datatypes, there will be an explanation and an as to whether it's required, and the default values, if any, for optional parameters.

    Some special datatypes use other datatypes. These sub-datatypes are linked to another documentation page containing a table listing the parameters and descriptions of them. Following each link can be overwhelming. For some special datatypes, the table for the main sub-datatype is included on the same page. Otherwise, you may have to drill down to each datatype's page — or open them in separate tabs in your web browser.

  • Returned Values: This table will list the fields you may request in the results when executing a function. This is almost always a special datatype. In which case, a table listing the fields is shown. However, for a few functions there are no special datatypes used. For example, there may be a boolean to indicate success or not for mutations, or a string for the only straightforward return value of a function.