Access and Use the Connect API Explorer

The application contains an interactive API explorer that allows you to explore the schema, format and run queries and mutations, and view responses.

The Connect API Explorer includes schema validation, so you can test a query or mutation before embedding it into a third-party application. It also includes the OneGraph GraphiQL Explorer plug-in, which is a query builder that assists users, both new and advanced, in quickly and easily generating queries and mutations with a graphical representation of the data fields and objects, and helps avoid the frustration of incorrect syntax.

The Connect API Explorer page contains four panes, as shown in the following figure, and described in the following list.

• Explorer pane: New query builder for automated assistance in constructing queries and mutations.

  Note

  To close the Explorer pane, click the X button. To reopen this pane, click the Show explorer button in the Editor pane.
• Editor pane: Area for constructing, formatting, and running queries and mutations.
• Results pane: Contains query and mutation results.
• Documentation Explorer pane: Documentation details for all query and mutation endpoints and their associated arguments and fields.

Each time you enter the Connect API Explorer page, the Explorer pane will begin with a default query under the “Me” argument related to data associated with you, the user.

To access the API through the Connect API Explorer page, and to manipulate queries and mutations:

1. On the Portal Home page, under Portal Management, click Connect API Explorer.

2. To create a new query or mutation, in the Add New field, at the bottom of the Explorer pane, select Query or Mutation from the list, and then click the + sign.

   The new blank query or mutation will appear in the Explorer and Editor panes with a default name.

   When you modify data through the Connect API Explorer page, you change the data in the application. We recommend that you test any mutations in a non-production environment or using non-production data.

3. To copy an existing query or mutation, to the right of the Name field, hover over and click the Copy button, as shown in the following figure.

   

   A duplicate copy will appear under the existing queries and mutations in the Explorer and Editor panes.

4. Enter a unique Name. The change appears in the Explorer and Editor panes.

   
   
   
   Note
   
       You can manipulate multiple queries and mutations simultaneously by giving each operation a unique name.  It is best to give your query or mutation a unique name to help identify their function.
   
   
   
   

5. In the Explorer pane, expand the cases list by clicking the expand arrow, as shown in the following figure.

The cases argument is added to the Editor pane with the proper syntax.

6. Select the check boxes for the id and name fields shown in blue text, shown in the following figure.

   The fields appear in the Editor pane in the proper location and surrounded by the correct syntax.

7. Select the check box for the active field shown in purple text, shown in the following figure, and then select true.

   Note

   When filtering with multiple values, such as multiple IDs, the builder does not support arrays. You must enter the multiple filtering values manually in the Editor pane.

8. Expand the sort field shown in purple text, and then do the following.

   a. Select the check box for the dir field, and then select Asc.

   b. Select the check box for the field* field, and then select **name**.

   The asterisk (*) following a field name indicates a required field. If selected, this field must contain a data value to filter on.

The query now contains all of the selected fields and filter options, as shown in the following figure.

9. Optionally, you can manually enter queries or mutations and their variables in the Editor pane. When entering them manually, be aware of the following:

   Note

   For more information about variables, see Substitute placeholders for static data: variables.
   • To see a list of fields, on a blank line in the Editor pane, press Ctrl + Spacebar. Press the arrow keys to highlight a value, and then press Enter to select the value.

     Note

     The query and mutation syntax is case-sensitive. And when entered in the Editor pane, the check boxes are automatically selected in the Explorer pane.
   • When entering multiple queries or mutations, use the format of query yourQueryName { } or mutation yourMutationName { } to keep each API call unique.
   • If a red squiggly line appears underneath any of the text, it means that schema validation has found an error in the API call. Hover over the red squiggly line to see more information about the error, as shown in the following figure.

   Note

   For more information about valid API structure, see the reference documentation.

10. To delete the query or mutation and start over, hover over the name in the Explorer pane, and then click the X button, as shown in the following figure.

    The query or mutation is deleted from both the Explorer and Editor panes.

11. To run a query or mutation, in the Editor pane, click the Execute query button.

    Note

    If you have multiple queries and mutations, a list will appear where you can select one for execution. However, all queries and mutations must be valid to run that selection successfully.

The results will appear in the Results pane.

For more information about queries, see Request data: queries. For more information about mutations, see Modify data: mutations. For examples of queries or mutations, see Data retrieval query examples or Import mutation examples.