GraphQL
Last updated
Was this helpful?
Last updated
Was this helpful?
The Appfarm platform has built-in support for querying your data through GraphQL. GraphQL can be used as a developer tool to view and modify data in your solution, as well as a method for exposing your data model to external parties for integration.
One of the powerful features available with GraphQL is the ability for the client user to construct a single query that returns only the data they need and nothing more. You do not need to define an API in advance, but simply select which object classes and data operations should be exposed.
GraphQL support is turned off by default and needs to be enabled at both the environment and object class level. The GraphiQL IDE can also be activated for testing queries and viewing data.
Follow these steps to enable GraphQL in your solution:
Under Environments, within each environment that you want to enable GraphQL:
Select Enable GraphQL.
Select Enable GraphQL Explorer if you also want to enable the GraphiQL IDE.
Under Global Data Model, select an object class that you want to expose via GraphQL. In the object class properties:
Select Enable GraphQL.
Edit the Endpoint Name if you wish. This is the name of the GraphQL object type.
Select the operations you wish to enable:
Enable Read
Enable Aggregate
Enable Create
Enable Update
Enable Delete
Repeat step 2 as required for other object classes.
Remember to deploy
Changes to object class properties, including GraphQL access, must be deployed to be represented in other environments.
Note: To access the GraphQL Explorer in a given environment, you must be logged in to the Appfarm client in that environment.
GraphiQL is a handy tool for working with your data during development and for verifying what data is accessible through GraphQL. Queries can be entered in the middle section and the response is displayed on the right-hand side. The Docs can be opened by clicking the book icon in the top left corner to show what object classes and operators are available. New tabs can be added by clicking the plus icon in the top right corner.
To access the GraphiQL IDE you must have first enabled GraphQL Explorer. Then, you can either:
Visit the URL https://SOLUTION-HOSTNAME/api/graphql/. Note that the solution hostname is environment-specific.
Under Global Data Model click Explore API and click the relevant environment.
The URL path of the GraphiQL IDE also serves as the API endpoint for that environment.
When using GraphiQL, you are logged in as your client user. Your data access permissions are granted by your role(s).
Third parties can integrate with your solution via GraphQL. The GraphQL API is located underneath the Appfarm Platform's security layer, so only authorized users can execute queries.
For a third party to integrate with your GraphQL API, you will need to configure their access.
Create a role and assign the necessary environment and object class permissions.
Create a service account and assign the newly created role.
Create an API key for the service account. Select the GraphQL Access checkbox. Store the API key in a secure location as it is not possible to view it again.
Provide the GraphQL endpoint (https://SOLUTION-HOSTNAME/api/graphql/) and API key to the third party.
To authenticate, they must either:
Add Bearer API-KEY as an Authorization header in the request.
Add token=API-KEY as a URL query parameter
The third party can then run GraphQL queries and mutations towards your GraphQL endpoint. Use GET requests for queries and POST requests for mutations.
POST request: The body must be a JSON object with query as a key and your mutation as value, e.g. { "query": "{project(filter:{projectNumber:{eq:123456}})}"}
The response is formatted as JSON.
For more information on how to use GraphiQL, see and .
GET request: You must add the GraphQL query as a with query as key and your query as value
Please check out the example on how to run GraphQL queries from an Appfarm App in . The example is also relevant for third parties wanting to integrate towards Appfarm's GraphQL endpoints.
