API Explorer lets you browse the UCare API documentation, build GraphQL requests and view the results without leaving UCare. It is useful when you are learning the API or developing an integration.
Requests use your signed-in UCare account and its existing permissions. You do not need to enter a separate API key to use the Explorer.
API Explorer connects to your church's data. Mutations can make real changes, including creating, updating or deleting information. Review an operation before running it.
Open API Explorer
- Sign in to your church's UCare account.
- Select API Explorer in the left-hand navigation. If the navigation is collapsed, hover over its icons to find the label.
- Use the editor to write your request. The results appear beside it, or below it when the Explorer is narrow.
The Explorer keeps the documentation, query editor and results together. The results pane is empty in this example.
Run your first query
To try the Explorer using your signed-in profile, replace the editor contents with this query:
query Me {
me {
firstName
}
}Select the blue Run button at the top right, or press Ctrl + Enter on Windows or Command + Enter on Mac. This example returns your first name.
Run, the selected operation and the request method are at the top right of the Explorer.
The button changes to Stop while an operation is running. For a subscription, use Stop when you no longer want to receive updates. Stopping a request does not undo work that has already completed.
Find fields and build a request
Use the icons down the left side of the Explorer. Hover over an icon to see its label; select it again to close the panel.
| Panel | What it helps you do |
|---|---|
| Documentation | Search and browse the available fields, arguments and types. |
| Query Builder | Choose fields and arguments to help assemble your request. |
| History | Return to operations you have run previously. |
| Collections | Organise saved operations so you can reuse them. |
Documentation is the first icon. History, Query Builder and Collections are below it.
The controls above the editor let you format a request, merge fragments, copy an operation or save it. Hover over a control to see its name. To keep an operation, choose Save operation, then choose or create a collection in the save dialog.
The editor tools sit above the request: format, merge fragments, copy and save.
If an operation uses variables, enter their values as JSON in the Variables editor below the request.
Choose the operation to run
If the editor contains more than one named operation, use the operation menu beside Run to choose one. Selecting an operation does not run it; select Run when you are ready.
The badge identifies the selected operation:
- QRY, in green: a query.
- MUT, in yellow: a mutation, which can change data.
- SUB, in purple: a subscription, which continues receiving updates until stopped or disconnected.
Review unfamiliar operations even when they are labelled as queries. The example above reads your own profile's first name.
View the response
Use JSON to inspect the response and any errors. The Table view is useful for responses containing a list; other response shapes may not have a table view. Use Copy response if you need to copy the result.
If a request reports an error, check its message, field names, arguments and variable values. Requests still need the permissions required for the information or action involved. If you ask someone to help, remove personal information from any response you share.
Understand the request method
Most of the time you can leave the method set to Auto. The Explorer chooses from the methods supported by the server. The button shows the method currently in use; its menu offers Auto and the available methods, which may include QUERY, POST and GET.
The QRY badge identifies a GraphQL query. QUERY in the method menu is an HTTP request method; these are separate choices. Mutations use POST. Subscriptions do not show a method menu.
If a browser filter or network service blocks a QUERY request, the Explorer can retry it using POST when supported. You can also select POST yourself. This does not resolve operation errors or missing permissions.
Run subscriptions in your web browser. They are not supported in the installed UCare apps.
Keep your saved work
Explorer history and collections use this browser's storage, kept separately for your UCare account and church. They do not automatically follow you to another browser or device. Clearing browser storage can remove them, and saving may not persist if browser storage is blocked or full.
Keep a separate copy of any operations you need to retain.